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u Without a doubt, the Premiere Resource Editor 
for the Mac OS ... A wealth of time-saving tools ” 

Mac User Magazine Eddy Awards 

*'A distinct improvement over Apple's ResEdit. ” 

- MacTeck Magazine 

*Every Mac OS developer should own a copy of Resorcerer. 

- Leonard Rosenthal, Aladdin Systems 

*Without Resorcerer, our localization efforts would look like a 
Tower ofBabeL Don't do product without it!* 1 

- Greg Gala nos, CEO and. President, Metrowerks 


“Resorcerer’s data template system is amazing,* 

- BUI Goodman, author of Smaller Installer and Compact Pro 

“Resorcerer Rocks! Buy it, you will NOT regret it. ” 

- Joe Zobkiw, author of A Fragment of Your Imagination 

“Resorcerer will pay for itself many times over in sa ved time and effort n 

- MacUser review 

“The template that disassembles 'PJCT’s is awesomeF* 

-Bill St el n be rg f a u t h or of Py ro! a n d PB Tools 

“Resorcerer proved indisperisible in its own creationF 

- Doug McKenna, author of Resorcerer 
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Version 2.0 


The Resource Editor for the Mac ™ OS Wizard 


ORDERING INFO 


Requires System 7.0 or greater, 
1.5MB RAM, CD-ROM 

Standard price: $256 (decimal) 
Website price; $128 - $256 
(Educational, quantity, or 
other discounts available) 

Includes: Electronic documentation 
60-day Money-Back Guarantee 
Domestic standard shipping 

Payment: Check, PO a, or Visa/MO 
Taxes: Colorado customers only 

Extras (call, fax, or email us): 

COD, FedEx, UPS Blue/Red, 

Intern ati onal Sh i pp i ng 

MATHEM/ESTHETICS, INC. 

PO Box 298 

Boulder, CO 80306-0298 USA 
Phone: (303) 440-0707 
Fax: (303) 440-0504 
reso rcerer@m a the m ae sthetics.com 


■ Very fast, HFS browser for viewing file tree of all volumes 

* Extensibility for new Resoreerer Apprentices (CFM plug-ins) 

* New AppleScript Dictionary Paete 1 ) Apprentice Editor 

* MacOS 8 Appearance Manager-savvy Control Editor 

* PowerPlant text traits and menu command support 

* Complete AIFF sound file disassembly template 

* Big-, little-, and even mixed-endian template parsing 

* Auto-backup during file saves; folder attribute editing 

* Ships with PowerPC native, fat, and G8K versions 


* Fully supported; it’s easier, faster, and more productive than ResEdit 

* Safer memory-based, not disk-file-based, design and operation 

* All file information and common commands in one easy-to-use window 

* Compares resource files, and even edits your data forks as welt 

* Visible, accumulating, editable scrap 

* Searches and opens/marks/selects resources by text content 

* Makes global resource ID or type changes easily and safely 

* Builds resource Hies from simple Rez-Iike scripts 

* Most editors DoRcz directly to the clipboard 

•All graphic editors support screen-copying or partial screen-copying 

* Hot-linking Value Converter for editing 32 bits in a dozen formats 

* Its own 32-bit List Mgr can open and edit very large data structures 

* Templates can pre- and post-process any arbitrary data structure 

* Includes nearly 200 templates for common system resources 

* TMPLs for Installer, MacApp, QT, Balloons, AppleEvent, GX, etc. 

* Full integrated support for editing color dialogs and menus 

* Try out balloons, ‘ictb's, lists and popups, even create C source code 

* Integrated single-window Hex/Codc Editor, with patching, searching 

* Editors for cursors, versions, pictures, bundles, and lots more 

* Relied on by thousands of Macintosh developers around the world 


To order by credit card, or to get the latest news, bug fixes, updates, and apprentices, visit our website,.. 

www.mathemaestheties.com 
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VIEWPOINT 


By Jordan Dea-Mattson 


WWDC Report 


Steve is in the House--. 

Flanked by giant posters featuring film great Francis 
Ford Coppola and Nobel prize winning physicist 
Richard Feynman, and with Big Band standards playing 
loudly in the background Sieve Jobs entered stage left 
and came forward to operate his patented il reality 
distortion field" on the masses of developers gathered 
for his keynote at this year’s WWDC. 

The question on everyone's mind as Steve started to 
speak was two-fold, First, everyone was wondering 
what Sieve would say. Like the Children of Israel 
gathered before Moses on Mount Sinai as he prepared 
to read the Ten Commandments, we all wondered what 
"laws" Steve would be laying down for us in die coming 
year. What would be in and what would be out? 

Second, in the back of everyone's mind was the 
omnipresent question that any sane person asks 
themselves when dealing with Steve Jobs: how will this 
story map into reality? 

Since the “Return of Steve” 1 have been present for 
each and every one of his keynotes. This one appeared to 
have even less spin and more substance than any of his 
previous keynotes. While some of It is announcements 
looked to the future, they were backed with solid 
deliverables in the here and now. 

The Master or Substance 

Steve's keynote, even more so than his previous 
ones, was a presentation emphasizing substance over 
style and hype, 

Steve kicked off his focus on substance by giving 
whal 1 have come to think of as his “State of the 
Company” address, where he lays out his proof that 
Apple is financially healthy, that things are getting 


better with each day, and that Apple isn't going away 
any time soon. 

At WWDC the “State of the Company" address was 
filled with comparisons of units, revenues, and 
earnings to the other major players - Compaq, Dell, 
Gateway - in the PC industry. The clear purpose of 
these comparisons was to illustrate that Apple is not 
only financially healthy, but that it is doing better than 
any other major PC company. 

As a reality check on Sieve's numbers - following 
WWDC - 1 performed an independent financial analysis 
of Apple comparing it Lo Compaq, Dell, and Gateway. 
13y almost every measure Apple is besting the 
competition across the board. The only two things 
holding back Apple s stock are a — not, given Apple’s 
history, totally unfounded — fear that things might 
return to the “bad, old ways” and a legitimate concern 
over how big Apple's business can grow in the face of 
the WiuTel duopoly. 

Following the “State of the Company' 1 portion of 
the keynote, Steve focused in on four areas of obvious 
importance to him and Apple going forward: Mac, 
QuickTime, WebObjects, and Mac OS X. 

The iMac section of the keynote focused on the 
twin themes of platform growth and Internet adoption. 

First, Steve laid out statistics showing that each 
quarter the iMac is bringing more first time buyers and 
WinTel switchers into the Macintosh fold. In the last full 
quarter prior Lo WWDC 45% of all iMac buyers where 
new to the Macintosh. This is important to us as 
developers, because new users by and large are the 
source of new software sales. 

Second, Sieve focused on positioning the iMac as 
the easiest way to get onto and use the Internet. In 

Continued on Page I/O 


Jordan Dea-Mattson (Jordan dea-mattson@wehappfoaory.eom> long a fixture at Apple's Worldwide Developer Conference and MacHack is a long 
time member of the Macintosh devdoper community. Me recently joined WehAppFactury, Inc., a WebGbjecis consultant and application developer, as 
President and CEO. Prior lo joining WchAppFactory, he was engineering manager for ePupcr Developer Technologies :n Add>e Systems Incorporated. 
He is probably past known for 13 year long tenure at Apple in various developer-related positions. His two major claims to fame are being the 
* Metro works Man” at Apple from 1992 to early 1999, and I he Jordan of "It's all Jordans fault! 1 ’ from MacHack. 
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The key to 

nt... 


Question: Is MacHASP USB* a 
software security key or a 
sales tool? 

Answer: It's both! 

MacHASP USB is the world's first 
software protection key for the 
iMac. It gives you sophisticated 
license enforcement and compre¬ 
hensive protection against illegal 
use... in other words, real security. 

Then it gives you a big selling 
advantage. 

With MacHASP USB, you can 
license multiple software modules 
and applications. You can instantly 
unlock or upgrade them in the 
field. Plus you can freely distribute 
demos. 

Bottom line: MacHASP USB locks 
out illegal users and unlocks your 


full sales potential - without 
getting in anyone's way. Call now 
to request a Developer’s Kit and 
our newly published guide to USB 
features and benefits. 

*For all USB-equipped Macs running an OS 
with USB support. Fully compatible with the 
ADB version of MacHASP. 

fturrMionusti 

MacrOS 

USA: 1-800-223-4277 
212-564-5678 
Inti: 972-3-6362222 

www.aks.com/mt 

ALADDIN 

KNOWLEDGE SYSTEMS LTD 


Mac software protection provider, Micro Macro Technologies, becomes part 
of Aladdin, giving its customers even better service from the number one name. 



NETWORK 

MANAGEMENT 


By John C. Welch 
Edited by Iletie Hoffman 


Networks 201 - Part 2 


Topologies, Signals, and 
Wires, Ob My! 


In the first article of the series, we 
went through the GS1 seven-layer network 
model, and discussed the purpose of each 
layer. We also covered the philosophy and 
reasons for the OSI model. Finally, we 
pointed out that there is a pseudo-layer 0 
in tlie model, that deals with the areas 
Ixaween stations or computers. This layer 
0 is the actual wiring or UP that connects 
the stations together, and this is what we 
will delve into this month. 


Scope 

As we talked about in the OSI article, 
Layer 0 is the media Ixaween stations in a 
network. Although Layer 1 is the Physical 
Layer, it actually only deals with the signals 
on the network, and ceases to function 
once you leave the transmitter, only 
picking up its function at the receiver. 
Liyer 1 is blind to everything in between 
nodes on a network. This is actually good, 
because it gives us a lot of flexibility we 
might not otherwise have in media types. 
Tiiis is not to say dial Layer 1 is completely 
independent of the media. If this were the 
case, then we could use Ethernet wiring 
and Token Ring network cards. Rather, as 
long as the connection interface between 
the media and the end node is correct. 
Layer 1 assumes that everything else is 


correct. So Layer Os scope is all I he wired and wireless media 
between node A and node B. In this article, we will stay on wired 
media. I covered 802.11 wireless networking in detail in the 
December 1999 MacTeeh, and recommend you read that issue 
lor information on wireless media and topologies. 

Wire Types 

logically, the first thing lo discuss in a wired network is Lhe 
wire. Wire is a bit of a misnomer, as when talking about copper 
network cabling, we are actually speaking of cable bundles. If 
we Kilk about filxr optic cable, then wire doesn't apply at all, 
Ixracuse in a fiber network, there is no wire. For ease of use, 
well use wire lo mean any physical path for a network 
transmission to travel on. 

Copper network cables arc the most common, even though 
fiber optic cable lias superior characteristics. Primarily, copper is 
cheaper than filler on a per-foot basis. Considering the total 
length of even a small network can easily reach well over a mile 
when all is said and done, tills is an important issue. Also, even 
with Gigabit networks Ixing implemented, topper still works 
quite well Copper is more simple to work with Lhan fiber, and 
it's much easier for a network administrator to quickly build 
copper cable when needed, than it would be for fiber. 

In spire of being somewhat harder to work with, and more 
expensive to buy, fiber has some dear advantages. It is capable 
of much higher speeds than copper, it is physically smaller, and 
it is immune to most electromagnetic situations that will cause 
great harm to copper networks. As an example, when i was an 
Administrator for a city in Florida, we had a building that was 
poorly grounded Every time there was a lightning storm, (in 
Florida that means daily), we had to replace the $6K WAN 
modems. After a year of this, we talked the city council into 
budget ing for a fiber optic connection to the building, Once that 
was done, it was the most stable building in the city. 


John Welch <jweleh@aer.eom> is the Mac and PC Administrator for AEK Inc., a weather and atmospheric science company 
in Cambridge, Mass. 1 Te has over fifteen years of experience at making computers work. I Its specialties are figuring out ways 
to make the Mac do what nobody thinks it can, and showing that the Mac is the superior administrative platform. 
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Coaxial Cable 

Sinee copper is the most prevalent wiring type, lei's look at 
that first There are three basic types of copper wiring for 
networks- Coaxial cable, shielded twisted pair or STR and 
unshielded twisted pair or l TR Coaxial cable, referred ro simply 
as coax, is a round, fairly thick cable with iwo conductors laid 
along the same axis, (hence the name Co-Ax). The inner 
conductor is a single copper strand, with a layer of insulating 
material around it. This is covered by a third layer of braided 
conducting material, such as aluminum, and this layer is covered 
by a coating of PolyVinylChloride (PVC) t or Teflon. A 
cross-section is shown in Diagram 1 below 


Sheath, 


Dtatectne 
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Conductor 
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Conductor 


Diagram L Coaxial Cable Cross-Section . 


Coaxial cable lias several advantages because of its 
construction. It is virtually immune to noise from outside sources 


such as fluorescent lighi fixtures and power lines. Coax also has 
excellent bandwidth capabilities. It has a ceiling of 2Gbps as 
long as the total cable length is less than 1km. These 
characteristics made coax a popular choice for network cable for 
many years. In fan, the original media specifications for Ethernet 
specifically required coax cable. Unfortunately, coax has a 
number of disadvantages which have led to its removal as a 
common network media. Coax is relatively fragile localise of all 
its layers. It can lie damaged or broken if it is Ixmt on loo small 
of a radius, or kinked. If it is subjected to even moderate 
crushing force, from say, a file cabinet, it easily breaks. Coax is 
also heavy, which made it difficult to use in a large network, due 
to the cost of supporting rite wire bundles, whereas twisted pair 
wire can normally be laid on top of a suspended ceiling. Also, 
coax tends to be fairly thic k, with diameters from 3/8 of an inch 
or more I King common. This causes problems in dense 
installations, as available space for wiring runs and closets is 
quickly consumed. In addition, the complex ilies of 
manufacturing coax made its overall cost much higher pci foot 
Lhan twisted pair wiring. Finally, coax cable is not flexible in its 
implementation. Due to ihe need for impedance matching and 
proper termination of the tines, coax networks are very sensitive 
to breaks in the line. Since most coax networks use a daisy chain 
style implementation, arty break in the line can easily bring 
down an entire physical segment of the network. Tins sensitiv ity 
also means that adding stations to an existing segment either 
requires bringing down part, or all of that segment, so that the 
new station and wire tan be added in, or the new .station must 
tap’ into the line. Tapping into tile line is where file connection 
for tiie node is clamped over the coax line, and a conducting 


Are you lost out there ? 


Can't find anyone to help you get your product to market ? 













spike in she connector punches into the conductors of the line, 
providing a connection point for the new node. When compared 
to the ease of plugging a node into a twisted pair network, this 
made continued use of coax hard to justify. 

TJils Is not to say that coax has no place in a modern 
network. In situations requiring high bandwidth, where fiber 
optic fines are not an option, coax is used extensively. 'Hie most 
familiar of Lhcse situations is for users of cable modems. Coax 
cable's high bandwidth and clean transmission characteristics 
make it ideal tor cable modems. Network and television signals 
can lx* run over the same line, and then filtered out at the 
appropriate desLinalit>n. 

Tw isted Pair 

The next type of network media Is twisted pair. This type of 
wiring is two wires, twisted around each ocher, Multiple sets of 
twisted pair wires are then combined in wire bundles. The 
number of .sets depending on the network requirements, from 
one pair, (phone networks) to eight pair bundles, (Fast Ethernet). 
The reason For twisting the wires is simple: Two long pieces of 
copper wire next ft) each other tend to he a much letter antenna 
than a carrier of network signals, by twisting the wires, this ability 
to pick up ambient electromagnetic radiation is destroyed, and 
Lite wires am then easily carry only die signals we wish, 

There are two types of twisted pair wiring: Shielded and 
unshielded. Shielded Twisted Pair (S'I P) wiring combines the 
lower costs and greater flexibility of twisted pair wiring, with the 
better shielding of coax, S I P takes a standard twisted pair cable, 
and wraps the wires in a layer of foil or braided metal as an extra 
layer of insulation. Although this gives STP superior protection 
from Radio Frequency Interference (RF1) and From things like 
light fixtures and power lines, it also adds greatly to the weight, 
thickness, and cost of the cables. IBM was one of the few 
companies to push STP. and as a result, you only see STP wiring 
in older IBM installations. 

Unshielded Twisted Pair nrj'P) is currently the most widely 
used wiring type in modern networks. It is lightweight, cheap to 
manufacture and install, and capable of speeds from 2Mbps to 
I Gbps. iriP is often referred to by different categories, such as 
Cat 3, or Cat 5, but in practice Cal 5 is the UTP type that you see 
mast often. The surprising thing a!>out IJTP categories is that 
there is really no other measure for assigning cable to a given 
category other than that cable's performance. Once the cable is 
built, it is tested at different speeds. If the cable is capable of 
reliable speeds greater than or equal to 100MHz, then it is a Cat 
3 cable. If the cable’s maximum speed is 20MHz, then it is a Cat 
t table. (Other criteria, such as twists per inch have been 
proposed, but they have been superceded by performance.) 
Currently, the only other category used besides Cat 5 is Cat 3. in 
older installations. Cat 1 anil Cat 2 were obsoleted in 1995, and 
Cal i offered such a small performance increase over Cat 3 that 
it was never really used. 

Regardless of die category of the cable, or the IAN type 
used, there are certain constants to keep in mind for UTP. 
The most important of these is the actual layout of the 


twisted pair wires in the connections. Normally, where 
devices such as hubs and switches are used, the type of UTP 


Both DCE and DTE originated when DTE devices 
primarily had outgoing connections, as in the 
connection from a terminal to a mainframe. DCE 
devices were used primarily for incoming connections, 
such as modems, or communications front ends\ In a 
modern network, any device can he either the DCE or 
DTE end of the connection, so the terms are used more 
as an aid in wiring diagrams , or as a description of 
current use T than any practical need 


used is known as a straight connect cable. That is, lead 1 on 
one end of the cable connects to lead 1 on the other end, 
lead 2 connects to lead 2 and so on. This is also called a DCF 
to DTE connection. The computer connecting to the hub or 
switch is the Data Terminal Equipment, (DTE) side of the 
connection, and the hub or switch is the Data 
Communications Equipment, (DCE) side of the connection. 
A straight cable works for this type of connection, because 
the wires on the devices the cable connects have different 
functions. An example of this is shown below in Diagram 2. 
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Diagram J, DCE to DIE connection for I DBase-T UTP wiring. 


As the diagram shows, the physical devices on cither end 
are wired so that the transmit on one end connects to the receive 
on the other. This allows data to flow correctly. Although the 
diagram is for a JOMhps Ethernet connection, other network 
types would look the same. 

In situations where a DTE to DTE connection is needed, 
such as temporarily connecting two laptops together, or two 
hubs together, the straight type of cable won't work, so w r e use 
a crossover cable. This type of cable is named for the way the 
cables connect to different leads on different ends of the cable. 
The reason a straight cable won’t work is because if two DTE 
devices are connected via a straight cable, you would have 
transmit leads trying to send to transmit leads, while the 
receive leads did nothing. The crossover cable resolves the 
problem by making sure that the transmit connects u> the 
receive correctly, as shown in Diagram 3 below. 
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Diagram 3. Dili to DTE connection for 1 DBase-T IflV wiring. 

Fiber Optic Cable 

The final media/wire type is fiber optic cable. This type 
is different from copper-based media in both construction 
and signal transmission. Fiber optic cable, or just fiber, has a 
fairly simple structure. The outside is sheathed in plastic, the 
next layer, or cladding, Ls plastic, and the main conductor is 
high-purity glass or plastic. Filler is extremely thin compared 
to ITP cabling, because the light waves that pass through it 
have a wavelength, or size measured in nanometers, or 
billionths of a meter The cladding and sheathing are 
measured in microns, or millionths of an inch, so a bundle of 
fiber the same size as an average UTP cable lias many more 
conductors than the UTP cable, and far more capacity* 
Usually, LAN grade fiber is known as 62.5 micron glass, 
(conductor) diameter fiber. You also will see it expressed as 
62.5/125 micron glass, where the 62.5 is the conductor size, 
and the 125 is the diameter of the cladding. Fiber optic cables 
are used in pairs, each cable carrying light pulses in a single 
direction, either to or from a station on the cable. This is due 
to current limitations in using light as a transmission signal 
There are two basic types of fiber, multi-mode and 
single-mode fiber. Multi-mode is named due to an effect 
created by the light source. Multi-mode fiber uses an LED 
(Light Emitting Diode as its light source. When an LED burns 
out, it is called a DKD, or Dark Emitting Diode, but these are 
less useful. LEDs are neither concentrated nor coherent light 
sources. That is, the light they emit is widely dispersed from 
the source* (not concentrated), and covers many different 
frequencies, (not coherent). This imposes some bandwidth 
and distance limitations on LED-driven fiber. Ideally, all the 
light from the LED would stay in the center of the conductor 
from the LED to the end of the cable. This is called axial 
travel, and is the desired way for the light pulses to travel 
within the cable. However, due to the lack of concentration 
of the LED’s signal, this doesn’t happen. Instead, parts of the 
light pulses reflect off of l he sides of the conductor. Although 
these reflections contain the same signal as the part of the 
beam still traveling axially, because they are traveling a 
different path through the conductor, they are now' known as 
modes. Also, due to this new direction of travel. the modes 
take longer to reach the end of the cable than the axial beam. 
This can cause problems on the receiving end, because 
instead of one single signal being received, the axial signal 
and all of the reflections are received at different times, which 
could appear to the receiver as different data than was sent. 


While all this bouncing around is taking place, 
remember that each time a mode passes through the axial 
signal, it can cause new reflections to take place, creating 
more modes, and potentially more confusion. The upside to 
multi-mode cable is that it, and rhe equipment it connects are 
substantially cheaper than single mode cable, in most 
situations, the individual cable lengths are only a few meters, 
so attenuation caused by ihe modes Is not an issue. Finally, 
multi-mode cable is thicker than single mode, so it is easier 
to work with. (If the interaction of the axial and reflected 
signals/modes seems confusing, this is due to the nature of 
light. Light can act as though it is particles or waves, 
depending on the context in which it is viewed. To 
thoroughly explain this would delve far deeper into 
advanced quantum physics than we have space or patience.) 

The second type of fiber is single-mode fiber. This uses 
a true LASER as its light source, usually an Injection Laser 
Diode OLD). ILDs have two advantages over LEDs: 
Concentration and Coherence. A laser tends to be a tightly 
focused beam of light, that has little dispersal over the 
distances used in a LAN. (Indeed, even at much greater 
distances. H is possible to send a laser from the Earth Lo the 
Moon, and have the dispersal diameter at the Moon be only 
about a foot.) This helps avoid the modes, and problems 
caused by modes that are normal for LEDs. Since LASERs, 
unlike LEDs, only emit a single frequency of light, they are 
said to be coherent. This allows for greater range, and also 
for the fiber manufacturers to better match the 1LD 
wavelength with the fiber, for smoother data transfers. The 
end result of this coherence and concentration is that even 
over many hundreds of meters, the beam does not spread 
enough to touch the sides of the fiber conductor. The beam 
is able to stay in the center of the conductor, or have near 
perfect axial travel, for the entire length of the cable. This 
allows all the information in the beam to arrive all at once, 
or in a single mode, hence the name. Single mode fiber 
conductors are usually between five and ten microns in 
diameter, with 125 micron cladding. Although single mode 
has greater range and data rales, it is also more expensive to 
manufacture, and install Single mode is most often used in 
situations where long distance is a necessity, such as 
telephone network backbones. Currently the maximum 
distance for single mode is around 30Km, although with the 
use of repeaters, lhat could be extended lo lOOKm. 

Since fiber optic cable requires light at a very specific 
frequency, or set of frequencies to work, it is worth our 
while to take a look at some of the characteristic's of that 
light. As it turns out, there are three specific frequency 
bands, about 25,000 to 30,000 GHz wide, that work the best 
for fiber. The reason for this is evident when you graph 
attenuation against wavelength, as shown in Diagram 4. 
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Diagram 4 , Attenuation m. Wavelength 
for IASFMs in fiber optic use. 


As you can set-, the Iwo largest wavelength bands, at 1,30p 
and 1.S5p respectively have the lowest attenuation aeruss their 
width. If you go much larger than 1.55|.u the attenuation rises 
last enough to cancel out any advantages gained by using a 
larger bandwidth. The reason for using the smallest wavelength 
band tlte 0.85|J bind Is a material one. At 0.8Sp, the lasers and 
the electronics using the lasers can ail lx:* made out of the same 
material, gallium arsenide, which makes manufacturing easier 
The savings in manufacturing balances out the auenuation 
caused by the higher frequency. Remember, wavelength and 
frequency are inversely proportional. The bigger the 
wavelength, the smaller the frequency. So now that we have 
covered the w iring types, the next step is to deal with how they 
arc laid out, or topology. 


ToPOUXilES 

The topology of a LAN refers to the layout of the wires and 
devices on that LAN. There are two types of topologies, physical 
and logical. The physical topology 7 is the actual physical 
location of the media and stations on a LAN. This includes 
wiring closets, cable guides, wiring runs, etc. The logical 
topology is what we refer to when we talk about rings, stars, 
or,, backbones, Most often, the physical topology is only used in 
a general sense, as specifically describing the physical topology 
of a large LAN is unw'iddy at best. In this article, w r e will deal 
with generic physical topology types. 

Bus Typology 

Topologies fall under four basic types: Bus, Ring, Star, and 
Switched The first type, Bus, is the simplest of tile four, it is 
essentially a long main cable, or hucklxmc, that all stations conned 
to directly, Each end of the cable has terminators, the terminators 
are needed so tiiat any signal reaching them ends there, and does 
not relied back onto the line. Tills is also known as Voltage 
Standing Wave Ratio, or VSWR. (There are two reasons for 
avoiding VSWR, The first is that the reflections can induce errors in 
the data flow. The second is that the reflection can damage 
equipment. In higher power uses, such as RADAR, VSWR tan 
actually melt down equipment) Stations on the Bus transmit 
frames in all directions. If the frame readies a station that it is 
meant for, that station pulls the frame from die line. If not f the 
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frame continues until it reaches the terminator. Although simple to 
set up, and inexpensive* the Bus topology has been left Ireland for 
a numlrer of ieasons. It s inflexible, Ixreuuse adding a station 
means physically modifying the backlrene line via raps. This limits 
the numlxrr of stations on a line because you can only insert so 
many taps before the data degrades. This type* of physical 
connection also makes it hard to connect beickixmes together. The 
Ixicklxme itself is a single point of failure, Irecause if it is ait or 
damaged, all stations on that baddxjne are unable lo use the 
network. The bandwidth is shared among all stations, so if you 
have ten stations on a 10Mbps backbone, each station ends up 
with a 1Mbps connection, finally, the backlxme cable itself has to 
lx* fairly thick, and unwieldy, so as to he easily tapped. 

Ring Typology 

Ihe second tO|x>k)gy type is the King. At its most simple 
implementation, it is similar to a Bus, in that all stations directly 
conned to the ring. In that configuration, it also shares most of the 
Bus’s disadvantages Loo, However, in more modem uses, such as 
Token King, and 11)1)1, certain nxxiifi cations are made to tile 
physical topology, but the logical topology is still a ring. Using 
Token Ring for an example, the Ring itself is a set of two conductors, 
either copper or fiber optic. Hu* conductors attach to boxes called 
Media Actress Units or MAIN The MAIN function like hulls in an 
Ethernet network. Hie King conductors conned to ixais billeted 
King In and Ring Out indkilting the direction erf data (low. Each 
MAI ’ has a numlrer of ports that individual stations conned to, such 
as computers or printers kadi Ring can have multiple MAI s„ just as 
an Ethernet network can have multiple hubs, By using MAU\ the 
King gains a great deal of flexibility that it would < rtherwi.se not have. 
Since stations can lx* attached or removed lo the MAI s as needed, 
reconfiguring segments of the network is simplified. In this 
configuration, the Ring resembles a Star topology* although 
electronically. it is still a Ring, Also, MAI s can come with two Ring 
In and Ring Out ports each, allowing for redundancy. Hie King 
topology is not the most common, mostly lxx.itu.se it is only needed 
by a small numlrer of network types, the previously mentioned 
Token Ring and 11)1)1 among them. Like the Bus. bandwidth is 
shared among all stations on the Ring. 

Shir Typology 

The third topology is the Star. This is the most common, and 
most familiar LAN topology in use. In a Star setup* all devices 
connect to a central hub. Each device accesses the IAN 
independently of the others, That is* unlike a King or Ik is, on a Star, 
there is no backlxme that carries all the data to all tire stations. The 
hub functions as a pscudc>-backbone 5 but without the electronic 
requirements of a Ring or Bus, In a Star* hubs can lx* interconnected, 
to allow for greater flexibility of configuration and load balancing* 
The numlrer of stations on a given Star is limited by the size of the 
huh, and available bandwidth. Similar to the tins and Ring, 
bandwidth on a Star is shared by all stations. 

Switched Typology 

The final topology, Switched, is not so much a separate 
topology as a different implementation uf existing topologies. As 


we noted in the three previous topologies* they have one 
common problem: Shared bandwidth. Regardless of how much 
bandwidth you start out with, it is splii among all stations on that 
topology, resulting in much slower jrerfonnance ihan desired, 
One of the soiuLions to this is* the switch. The switch allows each 
station to have full access to die available bandwidth, at w hatever 
s[X“cd the switch provides to that connection. As an example* in 
a Star network* if the hub is capable of a maximum speed of 
lOOMhs* and lias 24 ports that are being used constantly, then 
each port only has access to 4,J7Mbs of bandwidth. Without a 
switch* the only solution is to buy more hubs, and place less load 
on each hub However* wiLh a sw itch, this changes, If you have a 
24-port 10Mbps switch* and the switch connects to a 100Mbps 
network, then each of the 24 devices on die switch has access to 
a full 10Mbps of I rand width. Even if the switch is on a 10Mbps 
network, each port still gets a full 10Mbps connection. IT is is 
lxxnu.se as each station on the switch transmits or receives, for die 
instant that the station is handling packets, it is the only station 
accessing bandwidth on the switch. In other words, the switch 
creates a temporary connection with only two devices on the 
network. This gives full access to bandwidth* and improves speed 
and reliability by reducing collisions. Any topology can I re- 
con verted into a Switched version for improved performance. 
Another advantage of the Switched topology is it creates virtual 
networks, and tracks these networks with internal tables based on 
things tike MAC addresses, The .Switched topology allows for 
greater configuration and control of traffic* through such 
technologies as VLANS, which we will look at in more detail in a 
later article. The disadvantage to a Switched topology is primarily 
expense, as switches are more exfxrnsive than hubs or MAUs. 

Conclusion 

Although we dealt with quite a few wiring types and 
topologies* we have covered the scope of Layer 0, Normally, you are 
not going lo encounter STP wire, or Bus topologies in your daily 
work. Coax was moving out of favor, but with the rise of cable 
modems, and broadband networks, you are likely to have to deal 
with it in lire future* I would also recommend doing some 
independent study on Hirer optic networks, as they are becoming 
more standard as network speed and reliability needs increase. As 
far as topologies are concerned, the Bus is rarely encountered in 
modem networks* but that could change as well. Stars* followed by 
Kings are the current main topology types* with Switched versions 
of each being extremely common. (Actually* there is a case for the 
Sw itch Ireing the most popular topology type* but that depends on 
who you ask. and what vendor they use.) In any case, switching 
networks are rising rapidly due u> their bandwidth efficiency and 
flexibility of configurations, 
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Introduction 

So Far in this series of articles on 
programming QuickTime, we’ve learned 
how to open movie Files and allow the 
user to interna with the movies in those 
files. We've learned how Lo perform some 
basic operations on movies, such as 
editing them and exporting them under 
new formats. We've also learned how to 
open and display image files and lo 
perform some simple transformations on 
those images. And, for good measure, 
wcVc managed to do everything in a fully 
cross-platform manner, so that our 
applications run lx>ch under the Macintosh 
operating system and under Windows, 
with exactly the same features. 

Now it's time to take an important 
step forward in our journey through 
QuickTime: it's time to learn how Lo create 
Quicklime movie files. Even though 
QuickTime supports a vast array of types 
of media (audio, video, text, sprite 
animation, vector image, virtual reality, 
and so forth), it expects that all of the 
media data and die information describing 
that data will be stored in a specific format, 
called the Quicklime movie file format. 
Tiiis means that once we learn the basic 
sequence of operations required to create 
files that adhere to this format, we can 


fairly easily apply that knowledge to create files containing any 
of these types of media data. For the moment, we T re going to 
restrict our attention to creating a QuickTime movie file with a 
single video Lraek. But the techniques we learn here will come 
into play over and over again in the future when we want to 
create movie files that contain sound data, text, music, sprites, 
and oilier types of media daLa. 

Happily, the Movie Toolbox provides a set of high-level 
programming interfaces that we can use to create movie files 
without having to know very much about the actual details of the 
QuickTime movie file format. We need to know some of those 
details, however, so well begin by surveying the structure of 
QuickTime movies and QuickTime movie files. Then well be 
ready to create movie files that exhibit that structure. 

The Striioihf of QuickTime Movies 

What exactly is a QuickTime movie? There are really two 
answers to this question. So far in this series, we r ve been 
concerned primarily with QuickTime modes as they exist in 
memory. That is in say, we’ve lieen working with items of type 
Movie that we can play, edit, attach movie controllers to, and so 
forth. We typically obtain these movies by opening QuickTime 
movie files, which exist on disk (or some other storage medium). 
The movie file contains the audio and video data that is 
presented to the user when a movie is being played, as well as 
other information (called metadata) that describes how that 
audio and video data is organized and synchronized. Of course, 
QuickTime isn’t limited to playing audio and video data, so we'll 
need a more general term to refer to the movie data contained 
in the movie file: lets call it media data. 

As a rough preliminary characterization, then, we can say 
that a QuickTime movie file is a file that contains the movie's 
media data and the associated metadata. (As well see later, a 
movie file might not actually contain the media data, but only 
references to the media data. For the moment, however, well 
ignore this possibility.) A QuickTime movie, on the other hand, 
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is a structure that contains information alxmi the media data* In 
effect, a QuickTime movie is just a bookkeeping device that 
contains the information necessary to retrieve the media data 
from the QuickTime movie file and present it to the user at the 
appropriate moment. 

The exact structure of QuickTime movies is private, [f you 
take a look into the header file Movies,h t you'll see that a variable 
of type Movie is a pointer to a MovieRecord structure, which is 
defined like this: 

struct NovicKecord I 

lon& data [ 11 ; 

1; 

All we can tell alx>ut the structure of a MovieRecord is that it 
contains at least 4 bytes of data. We can operate on movies only 
by using the application programming interfaces provided by 
the Movie Toollx)x, 

A movie consists of one or more (racks, plus some optional 
movie user data. A track has a starting time and duration, and is 
associated with exactly one kind of media data. So, for instance, 
a track might hold audio data or video data, hut not both. A 
movie can contain several tracks, each associated with a 
different kind of media data. Also, a movie can contain several 
tracks that are associated with the same kind of media data* For 
instance, a movie might have a video track and several audio 
tracks (perhaps in different languages). 

The structure of a track is also private, A v ariable of type Track 
is a pointer to a TrackRecord structure, which is defined like this; 


struct TrackRecord I 

long data III: 

A track contains a single media structure (or. more briefly, a 
media), which references, but does not contain, the media data 
associated with the track. Once again, as you've probably guessed, 
the structure of a media is private* A variable of type Media is a 
pointer to a MedlaRecord structure, which is defined like this: 

struct MediaRecordI 

j,on& data (I J: 

u 

Figure 1 shows a standard way of depicting the structure of 
a QuickTime movie. As you can see, this movie contains three 
tracks: two video tracks and one sound track. Associated with a 
movie is a movie time coordinate system , which provides a 
means to measure time in a movie. The basic unit of time 
measurement for a movie is the movie's lime unit , and the 
numlxT of time units that elapse per second is the movie's time 
scale. In the movie shown in Figure I, the time scale is 600, so 
the time unit is 1/600 of a second* The sound track is scheduled 
to begin playing after 1 second has elapsed in the movie, and 
video track 2 is scheduled to begin playing after about L5 
seconds have elapsed, QuickTime requires that all trac ks start at 
lime 0, but the track data can begin later in the movie; the empty 
space between lhe beginning of the movie and the beginning of 
the track data is called the track offset. 
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Figure l: The structure of a QuickTime movie 


Keep in mind that Figure 1 is intended to illustrate the 
logical structure of a QuickTime movie t not the actual 
arrangement of bytes in memory. To repeal, the actual structure 
of a QuickTime movie in memory is private. The only way to 
operate on movies, tracks, or media is to use the APIs provided 
by the Movie Toolbox. 

The Structure of QuickTime Movie Finis 

In contrast to the undocumented, private structure of 
QuickTime movies, the structure of QuickTime movie hies is 
completely public:. This means, among other things, thar 
QuickTime movie files can be built on any operating system, 
whether or not the Quick lime software is available on that 
operating system. That’s because a QuickTime movie file is just 
a sequence of bytes structured according to an openly 
documented specification. Note, however, that you don't actually 
have to know the details of that specification to build QuickTime 
movie files. The Movie Toolbox provides a set of high-level 
functions that we can use to build QuickTime movie files with a 
minimum of fuss. (Whew!) Nevertheless, it will be useful lor us 
to become acquainted wilh at least some of those details, if only 
to understand IxXter wliat it is we are building anti why we need 
to do certain things when building QuickTime movie files. So 
let's take a quick look at the structure of QuickTime movie files. 

It turns out that the basic structure of QuickTime movie files 
has evolved in the years since QuickTime was introduced. Files 
created back then will still play okay nowadays (at least on 
Macintosh computers), but we can make life easier tor ourselves 
and our viewers if we build files that conform to the currently 
preferred formal, which is single-fork, self-contained. Fast Start, 
interleaved movie files. Let's unravel that mouthful. 

Double-fork and Single-fork Movie Files 

When QuickTime was first released, back in 1991. it ran only 
on the Macintosh operating system. Accordingly, the default 
behavior of the Movie Toolbox was to build movie files that rook 
advantage of the dual-fork nat ure of files in the Macintosh file 
system, where each file has lx>Lh a resource fork and a data fork. 
The movie’s metadata was stored in the resource fork and the 
movie’s media data was stored in the data fork. This dean 
separation of metadata from media data meant that the Movie 
TooLI>ox could very easily find the metadata, parse it, and load it 
into memory as a QuickTime movie, without ever touching the 


media data. Figure 2 shows the original structure of QuickTime 
movie files as douhle-fork files, 
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Figure 2: A double-fork motnefile. 

Figure 2 also reveals a bit more about the internal structure of 
the data and resource forks of a double-fork QuickTime movie file. 
Consider first die data fork. The media data is contained in a 
structure allied an ait mi An atom is simply a collection of data 
preceded by an atom header, which consists of a four-byLe length 
value and a four-byte type. (1 he length value includes die 8 bytes 
occupied by the atom header) In this case, the atom is a movie 
data atom . whose Lypc is 'mdat’. The data contained in a movie 
data atom is one or more media samples, which together comprise 
the movie s media data. A media sample is a single element of 
movie data. (You can think of a video frame as a single sample.) 

Now' let's turn our attention to the resource fork in Figure 
2. As you can see, the resource fork contains lyoth a resource 
header and a resource map (which are contained in every well- 
formed Macintosh resource file). The resource fork also 
contains a resource of type moov, which is called die movie 
resource. The movie resource contains die movie metadata, 
which — lo and behold — is structured as an atom of type 
moov. This atom is called the movie atom. 

Ihe main problem with double-fork movie files is that they 
cannot easily be transported lo of>erating systems that do not 
support resource forks. To facilitate cross-platform deployment 
of multimedia content. QuickTime also supports single-fork 
movie files. In this case, the movie media data and the movie 
metadata are stored in one file (which is the data fork on 
Macintosh systems). Typically, the movie atom is simply 
appended to the end of the movie data atom, as shown in 
Figure 3, This movie file can be opened and played back on 
any operating system that supports the QuickTime playback 
software. As a result, we shall always build single-fork movie 
files whenever we create QuickTime movie files. 
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Figure £ A single-fork movie file. 

Before we move on, let's take a moment to try to prevent 
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some potential confusion. As weve just seen, Ixuh single- and 
double-fork movie files store the movie metadata in an atom of 
type moov\ called the movie atom. In a double-fork movie file, 
the movie atom is contained in a resource of type rnoov, called 
the movie resource. Indeed, in a double-fork movie file, the 
movie atom and the movie resource are identical. Tins fact has 
encouraged some developers 10 use the terms ' movie resource* 
and “movie atom 51 interchangeably. But this is unfortunate, since 
(as you can see) there is no movie resource in a single-fork 
movie file, but there is a movie atom. 

The potential for confusion is compounded by die fact Lhat 
lire Movie Toolbox includes the function Add Movie Resource, 
which we will need to call to add the movie atom to our single¬ 
fork movie files (see, for instance, Listing 1). Originally, 
QuickTime did not provide a way to create single-fork movie 
files directly. Instead, you had to create a double-fork movie file 
and then call the function Flatten Movie Data to make a single-fork 
copy of dial double-fork movie file, tn QuickTime 3-0, 
AddMovieResource was revised to support direct creation of 
single-fork movie flies. Nowadays, Add Movie Atom would perhaps 
Ik a better name than AddMovieResource. 

Fast Start Movie Files 

Notice that, according to the default structure of single-fork 
movie files (as shown in Figure 3), the movie atom is stored at 
the end of the file, The reason for this is quite simple. Typically, 
we build a new QuickTime movie file by creating an empty 
movie file, adding new tracks to the movie, adding a new media 
to the track, and then adding some media samples to the media. 
As this process continues* the Movie Toolbox keeps track of the 
gradually changing metadata, which can be added to the movie 
file only alter all the movie data has been added. The movie 
metadata is rather like a cargo manifest, which can be deemed 
accurate only after all the cargo has been loaded. 

In .some cases, this default location of the movie atom is 
unproblematic. When die movie file is load (that is, stored on a local 
hard disk, CD-ROM, or other random-access storage device), 
QuickTime can search through the Hie quickly enough that it can 
find the movie metadata — which it needs in order to start playing 
the movie — with no appreciable delay. But when the movie file is 
being sent across a local area network, or indeed across the Internet, 
it Isn't generally possible to randomly access the file's data in this 
manner, This means that QuickTime cannot start playing remotely- 
stored movies until the entire movie has been downloaded from the 
remote storage device to the local playback machine. 

To remedy this situation, QuickTime provides support for 
creating fast Start movie files, in which the movie atom is stored 
as the first atom in a single-fork movie file. Figure 4 shows fhe 
structure of a Fast Start movie file. As you can see, the only 
difference between a Fast Start movie file and a default single¬ 
fork movie file is the location of the movie atom. T his simple 
change, however, is enough to enable QuickTime to start 
playing movies served from the web via HTTP or FTP before the 
entire movie has downloaded. 



Figure 4: A fast Start movie file .. 

To create a Fast Start movie file, we need to create a single¬ 
fork movie file and then call FlaitenMovieData with the 
flattenForceMovieResourceBeforeMovieData flag. Well see how to 
do this later. 

Reference and Self-contained Movie Files 

Earlier 1 warned that a movie file might not actually contain 
the movie's media data, but only references to the media data, 
which is contained in some other file (called the media file). A file 
that has this characteristic is called a reference mom file. Figure 5 
illustrates this possibility. Here, the movie file itself contains only 
the movie atom, which contains references to Lhe media data. 
Reference movie files can Ik useful if you want to share some data 
among mo or more Quicklime movies. By referencing the shared 
media data instead of containing copies of it, the associated 
QuickTime movie files can take up substantially less space. 


Movie file 



Figure 5: A reference movie file and its target media file. 

It’s also possible for a reference movie file to refer to media 
data in more than one media file. Indeed, tt 3 s possible for a 
reference movie file to refer to media data in some media file as 
well as media data contained in Lhe reference movie file itself. 
(The first kind of media reference is called an external reference, 
and the second kind is called an internal reference.) QuickTime 
really doesn't care where the media data is stored, as long as can 
resolve the references to that data at playback time. 

The opposite of a reference movie is a self-contained movie 
file In a self-contained movie file, all rhe media data needed for 
playing tire movie is contained in the movie file itself. Or, put 
another way, a self-contained movie file does not depend on any 
other files. Or, put yel another way, all media references in a self- 
contained movie file are internal references. Figure 6 shows a 
self-contained movie file, in which the media references in the 
movie atom are resolved to media data in the movie file itself, 
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Figure 6: A self-contained movie file . 


If you've got it reference movie file, you can create a self- 
contained movie file from it by calling FlattenMovieData. (Note, 
however, that it’s possible to build a self-contained movie file 
directly, without having m create a reference movie file and then 
call Flatten MovieData to create another movie file.) 
Flatten Movie Data resolves all media references and copies the 
referenced data into the movie file itself. For this reason, a self- 
contained movie file ts sometimes also called a flattened movie 
file . But this terminology can be confusing, since 
RattenMovieData also makes copies of any media data that is 
multiply referenced by internal media references. That is to say, 
if a self-contained movie file contains several internal references 
to the same media data, then the result of calling 
FlattenMovieData on that file will be a larger movie file that 
contains several copies of the referenced media data (each of 
which is referred to exactly once by the movie atom). So, if we 
reserve the term “flattened” for any movie files that might have 
been created by FlattenMovieData, it follows that not all self- 
contained movie files are flattened movie files. 


To make matters worse, the term “flattening*’ is sometimes 
also used to refer to the process of converting a double-fork movie 
file into a single-fork movie file. So, in this parlance, a flattened 
movie file Ls simply any single-fork movie file, whether or not it 
contains any external media references. Perhaps the best course of 
action is simply to avoid using the term "flattened" altogether 

Interleaved and Non-Interleaved Movie Files 

We’ve almost reached the end of our survey of QuickTime 
movie file organizations. There is only one final twist that we 
need to consider. Typically, when we build a movie file that 
contains more than one kind of media data, we add the media 
samples for one kind of media data (for example, video data) 
and then we add the media samples for another kind of media 
data (for example, audio data). The resulting file is a noti- 
interleaved movie file, as shown in Figure 7. 
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Figure 7: A mm-interleaved movie file . 


Non-interleaved movie files do not provide optimal 
playback from slower storage devices (such as CD-ROMs) where 
seeking can be expensive, or in situations (such as network 
playback) where random access to the file data is not possible. 
Instead, it's better to reorganize the media data so that it’s 
arranged in temporal order. That is to say, we d like the audio 
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and video data for the first second of the movie to lx- stored 
dose to one another, followed by the audio and video data for 
the next second of the movie, and so forth. Figure 8 shows an 
interleaved movie file that has the desired structure. 
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Figure fit An interleaved movie file. 

To create an interleaved movie file, we typically create a 
single-fork movie file and then call Flatten Movie Data. By default, 
Flatten Mo vieData interleaves the media data to ensure optimal 
movie playback. You can override this default behavior by 
passing the flatten Dont Inter leave Flatten flag to Flatten Movie Data: 
the result would be a self-contained, non-interleaved movie file. 

Cheating QuickTime Movie Files 

Our ultimate goal* then, is to create a single-fork, seif- 
contained, Fast Start, interleaved movie file. The resulting file 
will play on all platforms that support QuickTime movie 
playback and !>c suitable for distributing on CD-ROM and over 
the Internet. To simplify things, were going to create a movie 
file that contains a single video track. Well postpone adding 
other kinds of tracks to future articles. 

To create a single-fork, self-contained Quicklime movie 
file, we typically need to perform eight operations, in this order: 

* Create a new* empty movie file and a movie that references 
that file ( CreateMovreFile). 

* Add a new track to that movie (NewMovielrackl 

* Add a new media to that track iNewTrackMediat. 

* Add media samples to the media, 

* Insert a reference to the media segment into the track at die 
desired offset (Insert Media IntoTrack), 

* Add the movie atom to the movie file (Add Mo vie Resourced 

* Close the movie file (CloseMovieFile). 

* Dispose of the movie (DisposeMovie), 

If we want the final movie file to l>e either Fast Stan or 
interleaved, we need to perform one additional operation: 

* Place the movie atom as the first atom in the movie file, and 
interleave the media data (FlattenMovieData ). 

As you can see, each of these steps — except for step 4 — 
can lie accomplished with a single Movie Toolbox function. 
We're going to use these eight functions, in this order* over and 
over again as we build different kinds of QuickTime movie files, 
here and in future articles. So you should take a moment to burn 
these steps into your memory. The only real differences between 
building, say, a video movie file and □ wired sprite movie file 
concern step 4, adding media samples to the media. Fven 


though the movies in those two kinds of files have radically 
different playback characteristics, the fundi menial structure of 
the QuickTime movie files is the same, and so the way we build 
those files will lx. j essentially the same. 

Let’s lake a preliminary look at how this all conies together 
in practice. Listing I defines the function 
QTMM _CreateVideoMo vie. which is rite routine used by our 
sample application QTMakeMovie for building a QuickTime 
movie file. QTMM„CreateVideoMovie begins by calling the 
framework function QTFrame PutFile to elicit from the user a file 
name and location for the new movie file. Then 
GTMM^CreateVideoMovie calls the Movie Toolbox functions 
listed above to build a movie file. Step 4, adding media samples 
to the media, is handled by the application function 
QTMM_AddVideoSamplesToMedia, which is sandwiched between 
the two calls BeginMediaEdits and EmdMediaEdits. 


Listing I: Creating a Quick l ime movie, 

QTMM C.rmtrVitlet>Movtc 

OSErr QTKK CreateVideoMovle (mid) 

I 


Movie 

suyKovie ® NULL; 

Track 

ayTrack * NULL; 

Media 

myHedia ^ NULL: 

FSSpec 

tayPilet 

Boolean 

raylsSeiected “ false; 

Boolean 

mylsReplacing - false: 

String?tr 

my Prompt 

QTUti1 a JSoovertCToPascalString(kUewMoviePrompt); 

StringPt t 

my FI leNaflie w 

QTUtily^EJolivet iGToPa&calSt f ing(kNpwMovieFilfiNaiae) 

long 

iiiyJ’U a ga - c teat tMovicF 31 oDel * t eCu r F11 p 
c reat eHoviePile DuntCrcaloRcsFlie; 

abort 

myResReiNurn - 0: 

short 

myResID * movieInDataForkKeEiD; 

OSErr 

my Ere “ noErr; 


ft prompt tlx user for new Hit name 
QTFrasie_PutFile (my Prompt, myFilt'Ntiaie, fcmyFilc, 

&tnyisSelected, l sKt*p lacing); 
ffiyErr = mylsSeletted ? noErr : userCanceledErr: 
if (myErr != noErr) 
goto baits 

ft create a movie file for the tJfMimwkm movie 

myErr = CreatettovieFIlef&aiyH le, sigHovfefUayer, 

smCurrentScrlpt* myFlaga. &niyRe$RcfMi,m, &myKavie): 
if (iiyErr !“ noErr) 
goto bail; 


// create ctic movie tracts anil media 

loylrack “ NcwMovLeTnjekfrayMovie, 

FIxRflt So(kVMpoTrackWidr li, 1), 
FixHatio{kVide6TnickH»?taht. I), 
kNoVolune); 

tnyErr - GetMoviesErrorO ; 
if (tnyErr 1“ noErr) 

&otG hail: 

myMedia = NowTrackMcd ia (myTrack. VtrianMediafype, 
kVideoTimeScak, NULL* 0): 
myErr CetMoviesError 0; 
if [myErr noErr} 

goto bail: 

if create the media sample* 
rnyKrr = beginMedlitEdits(ttyKiHlia); 
if (nryErr != noErrj 
goto bait; 

tnyErr = QTMM AddVideoSaffipl&fiToMedia (myMedia. 

kVideoTrackWidth. kVideoTrackHeight): 
if (myErr noErr) 
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goto bail; 

myEcr * EndMediaEd 11 a(myMedla); 

If (myErr !• noErr) 
goto bail; 

// add ihe media to the track 

my Err " InsortMedialntoTracktrayTrack, 0 f 0, 

GetKediaDuration(siyMed1 a). fIxed J ); 

if (myErr != naErr) 
goto bail; 

// add the movie atom to the movie file 

myErr ~ AddMovleEesource{myMovie h mYResRsfNom, SutyResID* 

NULL); 

bail: 

if [myResRefHuni 1 “ 0 ) 

Clos!fiMov3eFile(tryReflRefNiiiii); 

if (myMovie != NULL) 

UispoyeMovietmyMovie); 

free(myPrompt); 
free(myFileNaine); 

return (myErr) ; 

) 

In the following subsections, well gradually dissect Listing 1. 

Creating a New Movie File 

The first lhing we need to do to create a QuickTime movie 
file is create a new, empty QuickTime movie file, We can do this 
by calling the CreateMovieFile function, like this; 

myFiags “ createMoviftFileDeleteCurF11 e \ 

crGat#fov 1 gFH eDoniGrealeResFili?; 
myErr - CreateMovioFile(fcinyFIle. sigMoviePlayer. 

&mCur rent Script* myFlags. &myResRefNiJifl, &myMovie): 

Here, myFile is a file system specification that indicates the 
name and location of the new movie file. The second parameter 
specifies the creator type for the new file; in this rase, we re 
passing the constant sigMoviePlayer (defined in the file 
FifeTypesAndCreators.h) to indicate that we want the file's creator 
to be the QuickTime Player application (nee MoviePlayer). Of 
course, you are free to use any other creator type that you wish. 
The third parameter specifies the script in which the movie 
should be created; here, as always when we need to specify a 
script system, we pass the constant smCurrentScripl 

The fourth parameter to CreateMovieFile is a set of flags that 
modify the default behavior of CreateMovieFile, Generally, we 
will pass the two Hags indicated, createMovieFileDeleteCurFile 
and createMovieFileDontCreateResHle, which tell CreateMovieFile 
to delete any file already having the name and location specified 
by the myFile parameter and to create a single-fork movie file. 

The last two parameters allow CreateMovieFile to pass 
information back ro us, if it successfully creates the specified 
movie file. In Lite fifth parameter, it returns to us the file 
reference number for flic opened movie file. (Don't let the 
parameter name myResRefNum fool you: because we passed the 
createMovieFileDontCreateResFiie flag, die opened file fork is u 
data fork, not a resource fork.) Create Movie File accepts a flag that 
tells it not to open the newly created file, but here we want it to 
open the file so that we can add data to it. 

In the final parameter, CreateMovieFile passes back to us an 


identifier for a new, empty movie that references the file we just 
created. The parameter myMovie is of type Movie r which is 
precisely the sort of in-memory QuickTime movie that we’ve 
been using in previous articles. From here on in, we won t do 
anything directly to die movie file itself. Rather, we’re going to 
build die movie (by adding tracks and media samples to it) and 
then later use the Add Movie Resource function in write the movie 
atom into die movie file 

Adding Tracks lo a Movie 

Once we've called CreateMovieFile to create a new movie file 
and a new, empty movie, we need to add a track to the movie. 
We do this by calling the NewMovieTrack function, like this; 

myTrack = NevKevieTrack(myMovie* 

FixRatiofkVideoTrackWidth. 1), 
Fixkatio(kVIdeoTrackHeight, 1), kNoVolurae); 

NewMovieTrack needs to know which movie to add die new track 
to; here we pass the movie identifier that we obtained from the 
call to CreateMovieFile. NewMovieTrack also needs to know the 
dimensions of the new track. Since we're building a movie from 
scratch, well specify some predefined dimensions. The height 
and width are expected to be in units of type Fixed, so we’H use 
die FixRatio function to convert the predefined integer height 
and widths to that type, In the present case, die track Is 202 
pixels high and 1 52 pixels wide; 

kVideoTrackileight 202 

^define kVideoTrackVidth 152 

(These are die dimensions of a picture stored in the resource 
fork of the QTMakeMovie application.) 

The final parameter to NewMovieTrack is a value that 
specifies the desired volume level of die new track. Because die 
track we are about Lo create is a video track, we pass the constant 
kNoVolume to indicate that the volume level should be 0. 

Adding a Media to a Track 

Recall that a track is associated with exactly one media 
structure (or media). The media structure contains Information 
about die type and locution of the actual media samples that 
comprise the QuickTime movie data. We create a new media 
and associate It with an existing track by calling the 
NewTrackMedia function, like this; 

lay Media “ NewTrackMedia(myTtatk, VideoMediaType. 

kVideoTimeScale. NULL. 0): 

The firsi parameter is the track with which the new media 
is to Ik* associated; here of course we use the track dial we just 
created by calling NewMovieTrack. The second parameter 
specifies the type of media we want to create. As you can see. 
weve used the constant VideoMediaType to specify that we want 
to create a new video media. The Movie Toolbox defines 
constants for all media types for which QuickTime supplies a 
media handler (that is, a component that knows how to 
interpret a specific kind of media data). Here are a few of the 
common media tyfx-s defined in Movies.h: 
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TweenMediaType 


- F0UH^_CHAILC0DE( H vide') 

- F 0 UR_CHARJI 0 DE{ H stum h ) 

- F 0 UR_CHAR_CQDE( + text’J 
= FOUR CHAR CQDE( 4 musi‘) 

- FOUR CHAR CODErnncd 1 :) 
" F 0 UR_CHAR C 0 DK{ f sprt') 

- F 0 UR_CHAR_C 0 DE{TlshH 
= FGUR_CUAR_COni\ ( 'moov' ) 

- F0UR_C1IM_C01}E| “ L wen H ) 


Ovlt time, we will turn our attention to each of these media 
types and see how to build a movie that contains media data of 
that type. For the moment, as you know, were focusing on 
building a movie with video media data. 

The third parameter to the NewTrackMedta function specifies 
the media time scale, which is ihe number of media time units 
that elapse per second. The media time unit defines the media 
lime coordinate system. The media time coordinate sysLern is 
independent of the movie time coordinate system, which we 
discussed briefly earlier. In addition to interpreting the media 
data, the media handler for a track’s media also manages the 
task of mapping values from the movie time coordinate system 
to the media time coordinate system. For example, when die 
movie is ready to display a video frame, it passes the current 
movie time to the video media handler, which converts that time 
into the video media time coordinate system and then retrieves 
the video data at that media time. 

The movie time coordinate system is independent of the 
media time coordinate system largely to allow each media 
handler to work with time units that are appropriate to the kind 
of media iL is handling. Video media often uses a time scale of 
600 t which is evenly divisible into the most common frames-per- 
second values (8, 10, 12, 15* 24 r 30, and 60). Sound media 
typical ly uses a time scale equal to the sample rate of the sound, 
so some common sound media time scales are 11,025 (11 kHz), 
22,25454 (22 Id Iz), and 44,100 (44 kHz), 

The default QuickTime movie time scale is 600. Ihis value was 
selected to facilitate die mapping Ix^twecn die movie time coordinate 
system and the video media time coordinate system. Our sample 
application QTMakeMnvie uses 600 as die video media time scale: 

^define kVideoTimeScale 600 // 600 unils per second 

The fourth parameter to NewTrackMedia specifies a media 
data reference, which identifies die file (or other media 
container) that is to hold the media data for the specified track. 
Here we pass the value NULL, to indicate that the media data is 
to be stored in the file associated with the movie (that Ls, the file 
created when we called CreateMovieFile), It would be passible to 
specify some other file to hold the media da La for this track; 
however, since we want to create a self-contained file, well pass 
NULL here. For Lhc same reason, w r e pass 0 in the fifth 
parameter. If we were passing a non-NULL media data reference 
in the fourth parameter, we would use the fifth parameter to 
specify the type of da La reference. 
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Adding Samples to a iMedia 

We've been occupied so far with creating the oiovie 
metadata * the "bookkeeping details" — that will end up inside 
the movie atom in the QuickTime movie file. What we need to 
do now is add some media data to the movie file. The media 
data is what the user will ultimately see or hear when the movie 
is played, and what we would normally think of as the meat- 
and-potatoes of the QuickTime movie file. As we saw earlier, the 
media data is comprised of one or more media samples. 

To add samples Lo an existing media, we need to open a 
media-editing session. That is to say, we need to inform the 
Movie Toolbox that we want to change the media samples 
referenced by a track's media. We can do this by calling the 
BeginMediaEdits function, specifying the media we want to edit: 

my Err ** Be^inHed iaEd i tn {uyWfrd in); 

When we call BeginMediaEdits, die Movie Toolbox opens the 
media container, if it isn't already open, and makes sure that 
we can add samples to it In the present case, the media 
container is the QuickTime movie file that we created when 
we called CreateMovieFile 

Finally, we've done alt the groundwork that we need to do 
I id ore we am add some media data to our movie file. We've 
created a movie, a track, and a media, and we’ve opened a 
media-editing session. All that remains is to call 
Add Media Sample one or more times to add some media 
samples to the media container. Unfortunately, we haven't 
created any media samples yet. For the moment, let s defer 
going into those details, so that we can spend the remainder of 
this section focusing on the overall movie-making process. 
Let’s just call an applicationdefined function that adds the 
desired video media samples lo the media: 

myErr - QTOJ^AddVideoSamplesToMptj (niyMcdlo, 

kVideoTrackyidth, KVidt'oTrackHeight); 

Well spend the entire next section, "Adding Media Samples*, 
walking through the function QTMM_AddVideoSamplesToMedia. 

When we are finished adding samples to the media, we 
dose the media-editing session by calling the EndMediaEdrts 
function, like this: 

Jay Err ~ F,ndMcdiaEdit^(aiy Media); 

Inserting the Media Segment 

Once we've finished adding samples to the media and 
ended tlu* met! i a-editing session, we need to add a reference to 
some or all of that media to the track. In particular, we need to 
specify when in the track the media segment is to begin; we also 
need to specify the portion of the media samples to be inserted 
into the track. We can handle all of this with ihe 
InsertMedialntoTrack function: 

myErr = InsertKed laTntoTracktioyTrack. 

0, // lime in trade 

0, // beginning of media segment 

GevtiediaBurat ion (rcyMed i a). // duration of media segment 
fixed1}: 


We're not doing anything fancy here, but there are a few tilings to 
keep in mind 11 ic second parameter indicates where in the 
specified track the media data is to be inserted The value of that 
parameter is Interpreted in the movie time scale. So, if we want the 
video samples to start playing 2 seconds after the movie begins, and 
if the movie time scale is 600, then wc would piss the value 1200 
in the second parameter, tn the present ease, we want the video 
samples to start at the beginning of the movie, so we pass 0. 

The second and third parameters specify the beginning 
and duration of the media segment to w hich we want to insert 
a reference into the larget track. Both of these values should 
be expressed in the media lime scale. Since we want to insert 
a reference to the entire media data, we set I he beginning time 
to 0 and the duration to the value returned by the 
G et M e dta D u ration fu net ton. 

The last parameter to InsertMedialntoTrack indicates the 
media rate, which Is the rate at which the media samples are to 
be played. We wanl die samples to be played at their natural 
playback rate, so we pass the constant fixedb 

Adding the Movie Atom 

Now that we've inserted a reference to the media data into 
the movie's single video track, we've finally collected all the 
movie metadata we need, so we can add the movie atom to the 
QuickTime movie file. We do this by calling the 
AddMovieResource function, like this: 

myErr - AddHovieResQHrrpfinyMnvU*. Kef Hutu, kmyKeslD, 

NULL); 

AddMovieResource takes the information contained in the movie 
myMovie anil creates a movie atom, which it then appends to the 
file specified by the myResRefNum parameter. 

Originally, the third and fourth parameters specified the 
resource ID number and the resource name for the movie 
resource C which, you'll recall, was added to the file’s resource fork 
as a resource of type Tnoov). Nowadays, we are no longer 
interested in creating double-fork movie files, so we do not need 
to pass a movie resource name. Moreover, the Movie Toolbox 
now supports the constant movelnDataForkResID for the resource 
ID parameter, which indicates that the movie alum should be 
added In the data fork, not to the resource fork. So before we call 
AddMovieResource, well set the desired resource ID, like this: 

toyResID = tnovieTnDai aFarkReglD: 

Finishing Up 

We are essentially finished constructing a QuickTime movie 
file. Only two minor housekeeping tasks remain: we need to 
close the movie file that the Movie Toolbox automatically 
opened for us when we called CreateMovieFile, and we need to 
dispose of the movie that CreateMovieFile returned to us (and to 
which we subsequently added a video track). The function 
QTMM CreateVideoMovie ends with these lines of code: 

if (inyResRefNuia != 0) 

CJouftMovi^FitetmyReskefMum): 
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if (myMovle 1- NULL) 

OisposeMovieCmyHovie); 

Adding Media Samples 

In the previous section, we gradually dissected tile function 
GTMM CreateVideoMovie (defined in Listing 1) to learn how to 
create a QuickTime movie file with a video track. We postponed, 
however, the all-important task of adding media samples to the 
movie file. Instead, QTMM_CreateVideoMovie just called the 
function QTMM^AddVideoSamplesToMedia, which adds some 
video samples to the video track’s media. The reason we 
deferred our treatment of adding media samples is simply that a 
full consideration of that topic would have detracted from the 
main point of the previous section, which was to emphasize the 
general steps involved in creating any kind of QuickTime movie 
file. Now let's tie up die kxjse ends by seeing how to add some 
video samples to the media of the movie's track. 

To add a sample to a media, we really need only two things. 
First, of course, we need the media sample data. For a video 
track, the sample data usually consists of a compressed image. 
For a sound track, the sample data usually consists of some 
digitized (and possibly compressed) audio data. For a text track, 
the sample data consists of some number of characters. And so 
forth, for all the other kinds of media supported by QuickTime. 

Second, we need a concise description of the kind of data 
contained in the media sample. The media type (specified in the 
call to NewTrackMedia) is generally not sufficient to allow the media 
handler to know how to process the media samples. For instance, 
a video track can contain Images compressed using any one of a 
large number of video codecs (compressors/decompressors), and 
the track can have virtually arbitrary dimensions. For die video 
media handler to be able to display the video media samples 
correctly, it needs to know which compressor was used, the bit 
depth of the images, the dimensions of the images, and a handful 
or s«) of other pieces of information. 

The AddMediaSampie function expects us to pass it this 
information in a structure called a sample description . The file 
Movies.h defines a sample description like this: 


struct SampleDescripiion I 


iong 

descSize; 

long 

dataFormat: 

long 

resvdl: 

short 

resvd2; 

short 

dat&RefIndex: 


U 

The only two fields that we usually need to fill in are descSize, 
which specifies the size of the sample description, and 
dataFormat, which specifies the codec dial compressed the data. 
But except for some very simple media types, this structure Isn't 
complete enough. Instead, for video media data, well fill in an 
image description, defined in ImageCompression.h like this: 

struct ImageDfi&criprion t 

long IdSize; 

CodecType tType : 

long resvdl; 

short resvd2; 

S hort daxaRe fl n d ex; 


short 

version; 

short 

revlslonLevel; 

long 

vendor: 

CodecQ 

temporalQuallty; 

CodecQ 

spatialQnality; 

short 

width; 

short 

height: 

Fixed 

hRes; 

Fixed 

vRes: 

long 

daiaSize; 

short 

frameCount; 

Strll 

name; 

short 

depth: 

short 

clutID; 

As you can see, the first 

five fields of an image description 


are of the same type as the first five fields of a sample description 
(at least if you know that CodecType is defined as long), In effect, 
an image description is a sample description that contains some 
extra fields to hold information about video media. So. when we 
call AddMediaSampie to add a video media sample, well pass it 
an image description, suitably cast to a sample description. But 
we're not ready to cull AddMediaSampie quite vet. First wc need 
to create some video media data, the compressed images that, 
when decompressed, become the frames of our movie. Let s 
draw some images and compress them 

Drawing Video Frames 

Our video media data is going to consist of a series of 
individual compressed images. We are of course free to use any 
images we like. For fun, let's make the first image in the series 
a completely while rectangle, the last Image in the series a copy 
of the QuickTime penguin picture, and the intermediate images 
a progressively greater blend of the first and last images. Figure 
9 shows the first and Iasi movie frames, together with three 
intermediate frames. (In technical jargon, we're going to create 
a cross-fade between the first and last images.) 
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Figure 9; Some frames of the final movie file. 


Listing 2 defines the QTMM_DrawFrame function, which 
draws a frame of a specified height and width info a specified 
offscreen graphics world, QTMM_DrawFrame also takes as a 
parameter the sample number; it uses that number to determine 
how much blending of the first anti last images to perform. 

Listing 2: Drawing a frame of the movie. 

QTMM DtawFranc 

static void QTMM DravFraroe (short thfcTrackWidth, abort 
theTrackHeight, long theNimSample. GWorldPtr thoGWorld) 

{ 

Handle myllandle = NULL; 

char myDa t a 1kPIGTEiieKe ad e r Si ze J: 

static PicHandle myPicture “ NULL; 


26 


Making Movies 


MacTech • June 2000 






































static OWorldPtr nyCUotld = MULL; 

static GraphicsImportComponent rayImporter " NULL: 

Rect nyRect; 

RGBColor myColor; 

CoraponentResul t myErr - noErr; 

MaeSetRect(&niykect. 0* 0, theTrackWidth, theTrackfleight): 

if (myPicture “ NULL) I 

rayErr - NewGWorlcl'^myGWorid. kFixeiDepth. krayRect. NULL. 

NULL. (GWorldFlags)O); 

if (myErr [= noErr) 
goto bail; 

// read a picture from our resource file 
myPicture 31 GetMcture (kKcturelD): 

If (myPicture = NULL) 
goto bail: 

// use Mlinger to prepend ;i Si 2-hvic header onto the picture data; 

// this converts the PICT resource tbra into In-memory PICT file data 
// (sw* ice Hoc H lor an explanation of this) 
mydandle = (Handle}rayPicture; 

Hunger(myHandie. U. MULL. 0. rayUata. 

kPICTFiieHeaderSize): 

// get ;i graphics importer for the picture 

myErr = OpsnADsfaul t Component [ 

Graph i csTniporterGomponetitTypp, 
kQTPi 1 eType Picture* 
fcirayimporter): 
if (myErr 1“ noErr} 
goto bail; 


// configure the graphics importer 

myErr - GraphiesTmportSetGWorId{myImporter, myGWorlri. 

NULL): 

il (myErr ! = noErr) 
goto bail: 


myErr = GraphicsIraportSetBataHandle [my Importer. 

myHandle): 

if (myErr ! w noErr) 
goto bat!; 


myErr = CraphicslmportSetEoundsRect (niyImporter H imyRect); 
if (myErr 1= noErr) 
goto bail: 

// draw the picture into the source CiWorld 

myErr 3 GraphicGlinporrhrawCmyltnportor); 
if (myErr l- noErr) 
goto bail; 


// set the blend amount (0 - fully transparent; Oxffff = fully opaque) 
myCoior.red = (theNumSample - I) * 

(Oxffff / kNttmVid&oFramcfj I): 
myColor ♦ green - {iboNumSamplo l) * 

(Oxffff / kNumVideoErames - 1): 
myLolor.blue - (theNumSample - I) * 

(Oxffff / kNumVideoFrames - 1); 

OpColor(fiimyColor): 

// blend the picture (in the source GWorld) into the empty rectangle 
// (in the destination OWortd) 

CopyJJits ((HitHapPtr) ‘GetGWorldPixMap(myGWorld) * 
(EitMapPtr) 'GetGWoridPixHap (theCWorld) t 
&myRect, 
fcmyRect, 
blend. 

NULL); 

if (iheNumSample = kNumVideoFrames) 
goto bail; 

return: 

bail: 

if (rayHandle 1“ NULL) 
n i spaseHa ndle (itiyBandle): 


if (ayPicture !- NULL) 

ReieaseResourcet(Handle)myPicture): 

if (myimporter != NULL) 

CloneCoraponenr(ray Tmporter); 

) 


I won't say much more about QTMM.DrawFrarne, because 
it's not directly concerned with building QuickTime movie files. 
Basically, it reads an image from a PICT 1 resource, attaches a 
graphics importer to that image, draws that image into an 
offscreen graphics world* and then blends that image with the 
all-white image in the offscreen graphics world passed to 
QTMM_DrawFrame, You can work through the function if you 
like, or you can just trust me that, when passed values from 1 to 
kNumVideoFrames, it generates a series of images that includes 
the five shown in Figure 9 

Compressing Video Frames 

Now that we’ve got an image that we want to include as a 
media sample of our QuickTime movie file, we need to compress 
it so that it takes up less space on disk. If we didn’t do any 
compression on the video frames* each 152-by-202 pixel frame 
would occupy about 122,000 bytes* so our entire 100-frame movie 
file would occupy atxxU 12 megabytes. Thais a bit large for a 10- 
second movie, By compressing die movie frames* we can reduce 
rhe size of the final movie file to around 470 kilobytes (using JPEG 
compression) with no appreciable kxss of image quality. 

The only downside to compressing the movie frames (aside 
from any image degradation introduced by the image 


FINALLY 

An Easier Way to... 
ANALIZE X-10 SIGNALS 


^ nsofk &l 

2 G 00 Award V/innei 

Power Line SIGNAL ANALYZER 




Five tools in one 

allows easy analysis of 
complex X-10 system setups. 


♦ X-10 Code Identified 

♦ X-10 Signal Strength Meter 

♦ AC Power Line Noise Meter 

♦ X-10 Signal Dissecting 

♦ X-10 History Recorder 


June 2000 • MacTfxh 












Tools Plus 


WEB ten k 


Niain EM 




Page Charmer 2.0 
SI 39 


Scrlpter 2.0 

SI 79 


WebTen _ v 

FaceSpan 3.0 WebSpice Animations PowerKey 

ToolsPlus Lite si 79 WebSpice 1.000,000 S89 MkLtnux Rebound 


The products you need, with the prices 
and service you deserve... guaranteed. 


Power Tools for Programmers! 




Code Warrior Professional S put every thing you need far 
software development at your fingertips: project management 
toots, text and resource editors, source and class browsers, 
compilers, tinkers, assemblers, and debugger. Re tease 5 offers 
such features as RAD far Java, fester compile times, local and 
remote application debugging. IDE eaten sib i lily options arid 
even Lighter C(C i i compliance, Additionally, you cart create 
applications far Windows 95/98flNTT and Mac OS 8 ,x and Mac 
OS X from either host platform (available in versions hosted on 
Mac or Windows). 


< 




•H. 


Spotlight is the first Macintosh "Automatic Debugger" It can 
automatically locate run time errors in your code and display 
the offending source code line, Unlike similar tools on other 
platforms Spotlight is easy to use. No source code changes 
are necessary far application debugging. Spotlight can 
automatically check for wild pointers, memory I 
overwrites, underwrites, invalid dereferencing of handles, and 
even toolbox parameter validity checking - spotlight knows 
Macintosh verifying parameters to over 400 toolbox calls 


BugLink Solo is a database dedicated to collecting and tracking 
problem reports Ideal for the shareware developer BugLink 
Sofa allows you to distribute with your software BugLink 
Reporter, which can easily be configured to allow your end users 
to send structured bug reports direr fly to BugLink Solo Prom I 
users for exactly the information you need, send hnmidiate 
report conformations, customize a new database to each 
project, search for related bugs with a simple query. To kill bugs 
dead, you have to know where Lo Find Lhern 


$189 


Resoncener is the only supported general-purpose resource editor 
for Macintosh, Relied upon by thousands of Mac developers. 
Resorcerer features a wealth of powerful yet easy to use tools far 
easier, faster, and safer editing of Macintosh data fifes and 
resources, Whether you have to parse a picture, debug a data fork 
design and try oot Balloon Help, create a scripting dictionary, 
create anti-aliased icons, design and edit a custom resource with 
h 0,000 fields in It, create C source code to run a dialog, or any of 
hundreds of other resource related tasks. Resorcerer's magic will 
quickly save you time and money. 


VOODOO Server is a version control system far software 
developers using Metrowerks CodeWatrlor under Mac OS. 
VOODOO Server and the corresponding VOODOO clients (the 
included CodeWarrfar VCS plug-in and the VOODOO Admin 
application] are designed to offer reliable and robust version 
control features while minimizing the administrative overhead 
that usually accompanies version control If you're a single 
programmer or managing a team of developers, version control 
can make or break your project. Do it right, with VOODOO 

—iBan 

C++ Developer's Kit Standars was developed for everyone who, 
even without much knowledge of C + 4 language or software 
developing, wants to know the C+ + programming language 
with applications In I he QQSE, C + \ Developer's Kit explains 
software solutions foe C++ developers, programmers and 
C+ + students. 


—— 


































PO Box 5200 • Westlake Village, CA • 91359-5200 • Voice: 800/MAC DEV-1 (800/622-3381) 
Outside US/Canada: 805/494-9797 • Fax: 805/494-9798 * E-mail: orders@devdepot.com 


www.devdepot.com 

Master the Web! 


WebSTAR Server Suite 4.2 


WebSTAR Server Suite is a complete set of powerful and easy-to- 
use INtemet servers for the Mat OS. Effortlessly serve web pages, 
host email accounts, publish databases, and share files ■ all with a 
single application on one Mad WebSTAR Server Suite *s perfect for 
Internet or Intranet serving, single or multiple sites, smalll and 
large businesses - it's power and ease-oFuse saves any organization 


time and money. 



Award winning freeway 2.0 is simply the fastest and easiest way 
to create web pages. Professional weh designers worldwide use 
Freeway with its support for CSS and HTML 4,0. along with auto 
image slicing, image optimization, multilingual spelt-checking, 
HTMI Import, built-in FTP. and an exciting new Actions 
technology to create and maintain leading edge websites all 
without coding a single line l-reeway ships with a 390-page 
manual (5/5 Computer Arts Magazine). I ilemaker tutorial, a 
PhotoDisc offer with free a mages and more! 


freeway 

2.0 


.i taimaf j Sfeh - Sang 


Funnel Wfefa is the ultimate web analysis solution For professionals. 
Specifically designed for profiling web site usage and monitoring 
customer usage patterns. Funnel Web is ideal for examining server 
performance and online effectiveness. Funnel Web can analyze log file 
formats from any server. WebSTAR. WebTcn. even Unix or NT hosted 
ervers Discover the most popular pages on your site, track server loads 
& optimize server performance, prolife visitors based on organization, 
domain name, country, browser, etc. funnel Web does tL all! 



NetBarrier offers a Personal Firewall, Anti vandal protection, and 
Internet Filtering. Protect your machine from intrusions by Internet 
at Apple folk Incorrect passwords and individual actions ate 
togged, you are alerted to hostile actions, and Intruders are easily 
isolated. Internet Filtering allows you to be sure that passwords, 
credit card numbers, and other sensitive information can never be 
exported from your computer - the content itself is filtered before 
any transfer I (Rated 4 m ice by Macworld Magazine} 





$ 69.95 


...and great hardware solutions! 


Add two USB ports to your older Macintosh. Connect up ten 
127 devices to the Universal Serial Bus [USB] that is 
Apple's new standard for desktop connectivity. USB mouse 
devices, keyboards, joysticks, game controllers, printers, 
scanners - connect them all to your currenL computer, 
installs In minutes! 




Any serious gamer knows the superiority Of the flight Joystick But 
until now, Mac users have been hard pressed to find a gaming 
joystick with the kick-butt power and resilience they need. The 
MacSurfer USB Joystick fits that gap with features tike 4 trigger 
buttons, rapid fire finger trigger, har control, throttle, two way self 
centering, and complete customization for your game with ihe 
included Overdrive software. 




rurVHE U ASi 


4 





* -|ipH 

KhL-J 


ifs- 7 - ; f- - 

BsSnRjfc- 

























compressor) is that it takes time to compress the frames while 
building the movie file and ii also lakes time to decompress the 
frames during movie playback. But decompressing compressed 
video media samples is almost always faster than reading larger 
chunks of uncompressed data from a storage device, and it’s 
orders of magnitude faster than receiving larger chunks of data 
across a network connection. So compression not only reduces 
the amount of storage required by a movie file, it also enhances 
playback performance by shifting much of the work from the 
storage device or network connection to the CPli f 

QuickTime provides a rich set of services for compressing and 
decompressing images and sequences of images, principally 
provided by ( he Image Compression Manager (or, more briefly, the 
Oft. Right now we are concerned only with compressing our 
images into video media samples, and we tan handle this by using 
only two TCM functions, GetMaxCompressionSize and 
Compresslmage. GetMaxCompressionSize tells us the maximum size 
of our compressed image, given parameters that spec ify the size of 
the image to I*? compressed, the compressor and the desired level 
of compression. We will use that maximum size when allocating a 
data buffer, into which Compresslmage wUJ write the compressed 
image. As a bonus, Compresslmage also returns Lo us an image 
description whose fields have l>een set to die correct values for the 
image k lias compressed. As we've seen, well need that image 
description when we eventually call AddMediaSample 

I he first thing we need to do, before we can draw or 
compress our image, is create a new offscreen graphics world, 
which will hold the image drawn by QTMM_DrawFrame t So 
GTMM_AddVideoSamplesToM0dia begins with these lines of code: 

MacSetRectUfflyftecC, D. 0, theTrackWidth. LheTrackHnighi:)i 

utyKrr ” NewGWorLd(kmyGWorld, kPixelDepth, GunyRect, NULL. 

NULL. t&WorldFla&s)0); 

if (myRrr \~ noErrJ 
goto bail; 

inyPixHap - GetCWoirldFixMap (aryCWurld); 
if CmyFixMap — NULL) 
goto baili 

Loc kPixc 1 s(roy PixMa p): 

There is nothing fancy here; we just set the rectangle my Red to 
lire width and height of the movie frame and call NewGWorld 10 
create an offscreen graphics world of that size. Then we retrieve 
the pixel map asstx iated with that graphics world and lock the 
pixel map. Both GetMaxCompressionSize and Compresslmage 
operate directly on pixel maps, not on offscreen graphics worlds. 
Now we can call GetMaxCompressionSize, like this: 

oyErr - GeOlaxCoiipreusionSIzet tnyPIxMap, 
kmyReei, 

0, // lei 1CM choose depth 

eadecNannalQuaXity, 
myCodecType, 

(Coroprejssornomponent) anyCodec* 
{nnyWaxConprSize); 

As you can see, we pass GetMaxCompressionSize the pixel map, 
the image rectangle, an image bit depth, a compression quality 
specifier, the desired compression type, a codec specifier, and a 


pointer to a long integer. GetMaxCompressionSize will update 
that long integer with the maximum num!>er of bytes required to 
hold an image having the specified characteristics compressed 
using die specified compressor, 

Once we know die maximum size a compressed image wail 
occupy, we can allocate a buffer to hold the compressed image 
daLa, by calling NewHandte: 

wyComprDataHdl “ NewHandle (myNaxLCoEpt Size) ; 
if {myCuinprDaiaHd 1 “ NULL) 
goto bail; 

HLockHi (myConrprDatBHdi); 
myCamprDataFtr - *myComprDataildl; 

Notice that we lock the handle and then dereference it to obtain 
a pointer to the data buffer. Thai’s localise Compresslmage 
wants us to pass it a pointer, not a handle. 

We are almost ready to call Compresslmage. We need only 
one more thing, namely a handle to an image description. As I 
mentioned earlier, Compresslmage will fill in the fields of the 
image description we pass it; it will also resize the image 
description as necessary, so we’ll just pass it a handle Lo a four- 
byte block of memory: 

myl^ageDesc - (ImageBescriptionLiandleJNewtlaridleU); 

After we ve drawn an image into the offscreen graphics 
world myGWorld, we can compress ihai image by calling 
Compresslmage, like this: 

tnyErr = Ccuap teas Image { atyPixMap, 

Nmyitet't. 

LqdetNornta lQiial l.ty, 
ntyCodecType. 
mylmageDesc, 
jnyComprDataPtt); 

Compresslmage takes as parameters the pixel map of the 
offscreen graphics world, a rectangle that specifies die portion 
of the image to compress, the same compression quality and 
compressor type that we previously passed to 
GetMaxCompressionSize. the image description, and the pointer 
to a buffer, ll all goes well, myComprDataPtr will point to the 
compressed image data and mylmageDesc will be resized and 
updated. The actual size of the data buffer can be found by 
inspecting the dataSize field of the image description, 

Adding Video Frames to the Media 

We can finish this all off with one more step. Finally we are 
ready to call AddMediaSample to add the compressed image data 
to the media as a video media sample; 

tnyErt - AddMcd iaSamplef theMedia. 

myComprDai atfdl. 

0 . // no offset in daiit 

f “mylmageDesc) .dataSize, 
kVideoFrameDuratioii, // frame dural ion 

{SampleDes c rip tionHs mU e}©y Ima geDe sc , 

I. //one sample 

Q, // self-contained samples 

NULL); 
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The first two parameters here are the media to which we want to 
add die sample and the sample data itself. 'Ihe thud parameter 
specifies- the byte offset into the sample data buffer at which 
AddMediaSample should start reading the sample data: since the 
entire buffer comprises the sample data, we specify 0 as the byte 
offset Tile fourth parameter indicates ilie number of bytes to be 
copied inLo the movie file* As we saw just above, we can use the 
dataSize field of the image description to obtain that size* 

The fifth parameter s|xrcifies die duration, in the media time 
scale, of die sample being added to the media. We are giving 
each frame of the movie the same duration, which is specified 
by the constant kVideoFrameDuration: 

^define kVideoFramfiDuratIon kVideoTimeScale/10 


if (myErr noErr) 
goto bail: 


myCamprDataHd 1 = Nowllandle(rayHaxCoaprSize); 
if (myCoinprDatalidl — NULL) 
goto bail: 

ULockHi{myComptDataHdl): 
myCcspcDataFtr 55 ‘nyCamprftataHdl; 

mylmageDesc ~ (TmageDesLtiptlonHandleJNevHandleU): 
if (mylmageDeBc ™ NULL) 
goto bail; 

CctCWorld(&mySavedPort T &my SavedDevice); 

SetGWorId(myGWorld, NULL); 


for (myNiim Sample “ 1; 
Erasdlec LUmyKect); 


myNumSampie <- kNumVldeoFranest; 

dyNi]f>Sainplr++) | 


Each frame of the movie has a duration oFl/10 second. Since die re 
are K)0 frames in the movie, the entire movie will last 10 seconds. 

The sixth parameter to AddMediaSample is a handle to a 
sample description. As predicted earlier, we can just cast our 
image description handle to a sample description handle. The 
seventh parameter indicates the number of samples contained in 
the data buffer. The eighth parameter is a set of flags, which we 
can leave set to the default value of 0. Itie last parameter is a 
pointer to a rime value, in which AddMediaSample will return the 
media lime at which the sample was added. We don't care about 
that information, so we pass NULL. 

Listing 3 gives a complete definition of the 
QTMM_AddVideoSamplesToMedfa function, which adds 100 
samples to the specified media, thereby creating the movie data 
for our QuickTime movie file. 


Listing 3: Adding samples to a media, 

QTMM AddVkJtttiampIttToMcdia 

QSErr QTHH_AddVIdyuSctmpiesTGHedia {Media theMedia, short 
theTrarkWtdih. short theTrackHei&ht) 
t 


GWorldPtt 
PixKapHandie 
CodecType 

long 

long 

Handle 

Ptr 

Tma^DoscriptianHandle 

CSrafFtr 

CUllandle 

Rect 

OSErr 


my EWorld - NULL: 
myPixMap = NULL; 
myCodecType * fcJFEGCodecType: 
ayNsimS ample: 
rayKaxComprSize = GL; 
ayComprDataBd 1 ~ NULL: 
ntyComprDataPtr - NULL; 
mylaageDesc ^ NULL: 
mySavedPort = NULL; 
mySavedUevice - NULL; 
tayRect: 

myErr - noErr: 


KacSetRectf&royRect. 0 . 0 . theTrackWidth* theTraddleight): 

myErr = NevCWorldt&myGWarld, kF]xolDepth. &myKect. NULL, 
NULL. (GWurldFlags)0); 

if (myErr !* noErr) 
goto bail; 


myPixMap - CkHGWoridFixMaptiiyGWorld): 
if (rayPlxMap — NULL) 
goto bail: 

LoekPixeis(rayFixMap): 

myErr “ GetMaxCorapressioTiSizel myFixMap, 
fernyRect* 

0. // Id 10M choose depth 

codecNormalQuallty, 
myCodecType, 

(Comp r as s o r Compo n cjt t} any Cod e c, 
imyMflxComprSize); 


GTMM_DrawF rame (theTr ackWi d th , 1 heTrac kilo i ght. 

ftythinSaaple, myGWorld); 


myErr * Compress Image ( tayPixMap. 

fernyReet, 

c ode cNo ma i Qua lity, 
myCodecType, 
mylmageDesc, 
myComprDataPtr); 
if (myErr 1= noErr) 
goto bail: 

myErr “ AddMediaSample( theHedia, 
myComprDataHdl, 

0, // no offset in data 

{ 4 *myImageEesc) .dataSXze. 
kVideoFrameDuratiou, // frame dunuiun 
(SampleQcscr iptionliandleJmyliaageDear. 
i . // one sample 

0, //sdf-contamed samples 
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NUM.); 

if (myErzr 1 = nuErr) 
goto bail; 

I 

bail: 

SetCWor Id (i»y Saved Pm* t, isySavedDevice): 

if (mylmagelteisc 1“ NULL) 

Dis poseHandie ({Uiitid 1 <?) myTirtageDesc): 

if {myComptDataHdi !- NULL) 

D1 spoflfiHandle(myComprDataHdl): 

it (myGWurld I” NULL) 
DiapoaeGWorldfnryGWorld); 

return(myErr): 

I 


Saving a Mom 

We've now seen how to create a single-fork, self-contained 
QuickTime movie file- If we also want to create a Fast Sim or 
interleaved movie file, we need to take one more step and call 
FlattenMovieData on the new movie. Our sample application 
QTMakeMovie does noi take this extra step, but the application 
framework that QTMakeMovie is built upon does provide a way 
for us to do this. We simply need to open she new movie file and 
select the “Save As..,* menu item in the file menu. This will result 
in our application executing the QTFrame_SaveAsMovieFile 
function, which w ill prompt us for a new file name and location 
and then call FlattenMovieData to create a fast Stall, interleaved 
movie hie. The call to FlattenMovieData looks like this: 

tnyNerwMovie - FlattenMovieData { 
jnyMovie, 

f 1 at t enAd d M o V i vToOa l a Fo r k | 

flatten f or e eMo v i eRe s on r o i* Bt* F n r f Mo v i eD a t a > 

^yPlle. 

sOgftnvieP layer, 

siBSystemSrript, 

createcKovieFilcBeleteCurFi le | 
createMovleFUcDonrCreateResflie) l 

By default, FlattenMovieData Interleaves the movie data, so there 
is no need to do anything special to get an interleaved movie file. 
(Of course, since the movie vve built in this article lias only one type 
of media data, it's already interleaved) We gel a fast Stmt movie file 
by specifying the constant tlatte n Force Movie ResourceBefore Mo vieData 
in the second parameter 

This Month’s Cooil 

The Code folder accompanying this article contains the 
project files, source code, and resource data of the sample 
application QTMakeMovie, for both Macintosh and Windows. 
QTMakeMovie is just like our basic QTShell application, except 
that the Test menu contains a single menu item, ^Create New 
Movie" 1 , When the user selects that item, QTMakeMovie calls the 
QTMM CreateVideoMovie func tion (defined in Listing I) to create 
the “appearing-penguin" movie file. 

In addition to showing how to create QuickTime movie files, 
this month s code takes yet another important step forward To wit, 


tills code Is completely Carbonized, so that the compiled application 
runs both under the "classic" Macintosh operating systems tJ lot 
support Carlx>n (namely, Mac OS 8 and ( » anti under Mac OS X. 
Figure 10 shows a frame of the movie created by QTMakeMovie 
when opened by the application running under Developer Preview 
3 of Mac OS X As you can see r our movie window automatically 
uses tlie stylish new "Aqua" interface provided by OS X, 


@0 un.. 0 



p- » 


Figure l(k A movie window in Mat OS X. 

The code changes made in QTMakeMovie lo support 
Carbon are not very great, since I've been gradually moving 
toward Carbon-compliant APIs in previous versions of the 
application framework. The biggest changes concerned the 
project files for lire Macintosh version of the application. As 
you can see in Figure 11, all the Macintosh-specific libraries 
have been replaced by ihe single stub library Carbon Lib. 
(The downside here is that QTMakeMovie will not run on 
“classic 1 " Macintosh operating systems that do not have the 
CarhonLib system extension installed. ) 
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Figure ( t: lie pmjtxi window for the 
Carbonized QTMakeMovie. 


You can download the Carbon SDK (which includes boll) 
the CarhonLib stub library and the CarhonLib system extension) 
from <http://developerapple.com/sdk/>. 
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by Kas Thomas 


How to Write Plug-Ins for Adobe Acrobat 


The Acrobat SDK provides 
a bewilderingly diverse 
assortment of tools for 
manipulating PDF files 


Adobe's Portable Document Format 
(PDF) is the premier electronic document 
format for "rich content” on the web t not 
just because of its ability to convey the 
appearance attributes of a paper document 
(which ii is very good at, since ihc 
underlying technology is Postscript-based) 
but also because of its annotation features, 
hyperlink embedding, support for form 
widgets (and JavaScript), Unicode 
compatibility, security (encryptk >n) 
handlers, and accessibility features, (PDF 
is also evolving to become more adept at 
encapsulating document metastructure 
and private data types.) Access n> all these 
types of functionality is available to 
creators of PDF documents via Adobe 
Acrobat, the commercial version of Reader 
Unlike Reader, the full Acrobat product 
{street price; S200 or so) lets you mark up 
a PDF document in various ways, add 
links anti form fields, attach JavaScript to 
documents, etc. — and save the modified 
PDF file to a storage device. 

Most of the kinds of functionality 
you’d ever want to see in a PDF file can be 
added using Acrobat or created in the 
source file at the time of the document s 
creation (via MS Word, Prime Maker, or 


whatever). But in the PDF world, as in the world of Photoshop, 
Quark, After Effects, etc., there are times when the functionality 
you need just isn't available from the host application. In such a 
situation, it makes sense to consider a plug-in. 

As with its other flagship products, Adobe has 
incorporated a plug-in architecture into Acrobat to enable 
third-party developers to extend the functionality of lItc core 
product. Quite a few of the key features of Acrobat (features 
most users Lhink of as being "core functionality”) are, in fact, 
implemented in the form of plug-ins. For example, form¬ 
editing and form-fillout functions are done as plug-ins. Acrobat 
also uses plug-ins to implement weblinks, annotations, text 
Louchup, Quicklime movie attachments, scanning ("paper 
capture"), image-import, and quite a few other functions. 
(Check the plug-ins folder of your Acrobal installation.) 

Extending Acrobat’s capabilities via custom plug-ins is a 
powerful (and popular) way to give users extra control over 
PDF documents. But this capability comes at a cost. Learning 
to use the Acrobat plug-in API (one of Adobe's most complex 
APIs) can l>e a formidable challenge. There are well over 1,000 
functions in the Acrobat API; just finding the ones you need to 
carry out a specific task can be daunting. Suffice it to say, this 
is one API you won't learn in a weekend. 

Because of the sheer enormity of ihe API. ihere is no way 
I can give you more than a very abbreviated introduction to 
Acrobat plug-ins in the limited space available here. What 1 
can do is briefly outline the available tools, talk about a few 
of the most common idioms of Acrobat programming, and 
point you toward resources for further study. In addition, just 
so you won't think writing an Acrobat plug-in is totally 
beyond reach, we'll walk through the code fora small plug¬ 
in designed to do something at least vaguely useful: namely, 
add a text-based “watermark" to a page, in response to a 
menu command. 


Kas Thomas <kt@acioforms.com> has txvn programming in C and assembly on the Mac for more than ten years and consults 
For Adobe Systems and others on PDF-related development issues. You can read his work at Acroforms.com, HlanetPDF.com, 
and MightyWords.com. 
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Getting Started with the SDK 

You can download a copy of the Acrobat software developer's 
kit (SDK) from hnp://pa rtne rs.ado bexam/asn/do velo per/acrosdk/acrobat. html. 
The SDK is also available on CD-ROM to members of the Adobe 
Solutions Network Developer Program. (See 
http ://partner5, ado bexom/asn/devetoper for details.) The complete SDK 
requires over 30 megabytes of disk space, including 27 megs for 
documentation done. Example code comes in the form of Code 
Warrior projects for two dozen sample plug-ins and a handful of 
AppleScripts showing how to control Acrobat via IAC (Inter- 
Application Communication). The code is well-packaged, 
thoroughly commented, and well-summarized in a separate doefUe, 
5amples,pdf r which gives a brief overview of what each example is 
meant to demonstrate. 

The documentation that accompanies the SDK is so 
overwhelming that Adobe thoughtfully includes a '"Start Here” 
document as well as a flowchart-style roadmap diagram in 
which every box is a clickable link Lairing you to the appropriate 
dodile. T he roadmap occurs at the top of nearly every doefile in 
Lhe package, which is a nice touch. Just by clicking on various 
portions of the roadmap, you can jump from doc to doc. Of 
course, all the docs are PDE files with navigation bookmarks. 

The 213-page Acrobat Core API Overmew (Tech Note No. 

5190) is a good document lo start with, since it serves as a 
kind of giant FAQ for developers, explaining how the various 
components of the API work together. But the two most 
important docfiles in the package — the two you II spend the 
most time with arc The POP Reference Manual and the 
Acrobat Core API Reference. The 513-page PDF Reference 
Manual, also known as the PDF Specification, contains the 
formal language specification for PDF. Il spells out all she 
keywords, data types, architectural schemas, and syntax 
constructs that make a PDF file a PDF file, just as it would be 
hard to write a Netscape browser plug-in without 
understanding how HTTP and HTML work, il\s inconceivable 
that you would write an Acrobat plug-in without knowing a 
fair amounl about the low -level organization of PDF files. The 
PDF Reference Manual gives you this information. Plan on 
spending many hours reading it. 

Your primary reference manual for the plug-in API itself will 
be the 2,795-page Acrobat Core API Reference {Tech Note No. 

5191) . Yes, 1 said 2,795 pages. But don't worry, that’s sure to get 
bigger as Acrobat evolves. (Version 5,0 is set to appear sometime 
within tlie next nine months.) 

The Acrobat Core API Reference is not a book that you sit 
down and read cover to cover; rather, it's a reference you 
consult as the need arises. Inside it you’ll find descriptions 
(calling syntax, etc.) of the 1,100-or-so core routines dial make 
up the Acrobat API. You should understand that one reason this 
AIT is so voluminous is that it comprises the bulk of the library 
routines from which Acrobat iLself was (and is) wriLLen, Adobe 
uses these same routines internally for Acrobat development. 


What You Can and Can't Do 

IPs possible to write a plug-in for Reader as well as for 
Acrobat, (There are also mini-APIs for other products in the 
Acrobat suite: Capture, Distiller, Catalog, etc,) By default, any 
plug ins you write using Adobe's SDK will run under Acrobat 
(the commercial product) with no problem. Writing plug-ins for 
Reader is another matter. To get Reader to load your plug-in, you 
will need to obtain an Acrobat Reader Integration Key, Getting a 
key is a matter of filling out the Acrobat Reader Integration Key 
License Agreement (available on Adobe’s developer web site), 
signing it, and submitting it — along with a $100 payment (in the 
form of credit card only) — ro Adobe's Klamath Palls, Oregon 
group (which administers the developer programs). When you 
sign the agreement, you are agreeing to some fairly serious 
limitations as to what you will and won’t try to do in your plug¬ 
in. Specifically, you are agreeing never to include any of Lhe 
following kinds of functionality in your Reader plug-in: 

* Anything that would allow Reader to permanently modify, 
save, or write files, including PDF files, annotations for PDF 
files, form data, etc. Included in this is any functionality 
lliaL would enable another process (on a server, say) to 
save such data. 

* Anything that opens encrypted documents by bypassing 
normal security measures. 

* Anything that would display a PDF file in the window of 
another application. 
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* Accepting navigational commands from an application other 
than Reader itself. 

* Making use of any function cal! in the Forms HFT (host 
function table), 

* Implementing a replacement file system for Reader. 

* Anything that would remove the menu item that calls up the 
“About” screen for Reader. 

In other words, forget about making permanent c hanges to 
files (or doing disk writes) in a Reader plug-in. I lie whole idea 
is that Reader must remain read-only. (Otherwise it wouldn't be 
called Reader!) If your plugin does any of the things listed 
above, it has to be written as an Acrobat plug-in, targeting the 
commercial product only (which does modify and save files). 
This cuts the audience for your plug-in down substantially 
(probably to one percent or less of the audience of Reader). But 
there's still a sizable market left. In fact, the market for Acrobat 
plug-ins is surprisingly brisk, reflecting the product’s widespread 
use in prepress and enterprise settings. 


close windows, control the cursor's appearance, and drive just 
about any GUI-related action. But you cannot do file I/O, 
inspect or modify stream contents, or perform low-level 
operations on document internals From this layer. 



Figure l: Layers in the Acrobat API . 


Other Limitations 

Not everything you might want to do to a PDF file can be 
done using the Acrobat API anyway, it turns out. It's important 
to realize up-front that some things just ain’t be done. For 
example, let's say you wanted to implement a new image- 
compression codec. (PDF already implements JPEG. LZW, 
CCriT and Plate compression filters for image streams.) 
Unfortunately, the Acrobat plug-in API does not expose this 
kind of functionality purposely, to ensure maximum 
interoperability of PDF files. On the other hand, you can write 
an entirely new security handler, should you want to 
implement a different kind of encryption or passwording than 
is available by default in Acrobat. With security, interoperability 
is not a consideration 

Another kind of functionality you'll have trouble modifying 
is changing the way Acrobat draws filings to the screen. For 
example, if you want to change the default order in which 
various objects are drawn, apply a different kind of antialiasing, 
or improve the blitting performance — you're basically out of 
luck. These kinds of functionality aren't exposed in the API. 
That's not to say you can t try going outside the API; but in that 
case, maybe what you're trying to do would best be 
implemented as a helper app T system extension. WDEF, or 
something other than an Acrobat plug-in /terse 1 . 

Layers in the API 

Figure 1 shows how the Acrobat plug-in API is organized 
into a number of layers, designed to provide functionality at high 
and low r levels. At I he highest level is the Acrobat Viewer (AV) 
layer. In this layer are hundreds of routines for manipulating the 
Viewer's windows, menus, toolbars, etc, as well as for query ing 
the runtime environment. This is where, for example, you can 
call AVAppRegisterForPageViewClicksO if you want to track mouse 
hits. Most menu commands can be programmatically driven at 
this level. That means you can control the page view, open and 


The Portable Document Dryer implements the PDModeL 
which is an assortment of objects allowing access to individual 
components of the PDF file, such as annotations, bookmarks, 
links, or text selections. The objects in this model are generally 
opaque, which is to say they are neither pointers to data 
structures nor pointers to pointers. Access to the contents of 
objects that live at this level occurs via special accessorfunctions. 
For example, to gel an annotation you would use 
PDPageGetAnnotO; then you might inspect its flags with 
PDAnnotGetFlagsQand change the Hags with PDAnnotSetFlags{). 

At the very lowest level, the Cos Layer allows direct access 
lo si ream contents and page resources. (Cos is a recursive 
acronym for “Cos Object System, 11 ) Cos objects come in seven 
main varieties, mirroring the tiara types upon which PDF is built: 
booleans, numbers, names, dictionaries, streams, strings, and 
arrays. Cos methods go by names like CosArrayGetQ and 
CosArraylnsert(). They allow "subatomic particle” access it) the 
PDI file. Of course, as with other low-level programming tools, 
operating at the Cos level brings risk as well as rewards, As 
Adobe says in the Core API Overview : “Unlike the AcroView and 
PD Model layers, it is eery easy lo produce an invalid file using 
Cm methods. For this reason, they should not be used unless 
necessary, tor example to add private data to portions of a PDF 
file tliai cannot be accessed in oilier ways/ In other words, don’t 
go here unless you know dam well wlutt you are doing. And 
even then, look out for land mines. 

Cutting across all three major layers of API support is one 
additional layer, known as the Acrobat Support Layer. You can 
think of tills as a "utility” layer where you can find platform- 
independent functions fordoing file I/O. memory allocation, etc. 

PDFEdit Layer 

One "mini-layer we didn't talk about (which is shown in 
lag. 1 as a small layer residing midway between ihe PD Layer 
and the Cos Object level) is the PDFEdit Layer. In a nutshell, this 
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layer was created in order To provide easier (and safer) access to 
page contents than would otherwise lx" obtainable. At the PD 
biyer level, you have access to page content objects, but the 
objects are opaque and not always easy to modify using the 
available accessor functions, At the Cos level, on the other hand, 
you're dealing with raw streams consisting of arbitrary mixtures 
of page operators, numbers, and text. To manipulate those 
items, you have to “parse them out" yourself, which is not 
always easy. The PD Layer offers some parsing and enumeration 
methods, but in general the objects returned are not easily 
modified The problem is even worse than that, however. 
Resource handling is difficult because stream contents and 
resources are treated as disjoint entities. (A given piece of text is 
noi easily associated with its font resource, for example.) Also, 
stream data are often encoded via LZW or Plate compression. 
Merely retrieving the raw stream data usually isn't helpful 

The PDFKdit methods were invented to overcome these 
obstacles by providing access to low-level page comjjonenls in 
such a way that related items are grouped together, so that 
objects encapsulate any relevant informat ion about themselves. 
(A text object contains font information, for instance.) PDFEdit 
methods thus allow you not only m access but also create page 
contents, including whole pages, from scratch. Most of the 
relevant data structures are public (rather than opaque), so that 
you can manipulate attribute values directly. 

You can think of the PDFKdit biyer as offering much of the 
power of the Cos Layer, but with the safety and convenience of 
tile PD layer. 

PDSEdit Methods 

There is actually one more mini-layer in the Acrobat API, 
not shown in Fig. 1, called PDSEdit. The S T in PDSEdit refers 
to Structure. Prior to version 1.3 of the PDF Specification 
(which became current with the introduction of Acrobat 4,0), 
there was really no convenient way to store mctaxtriicturnl 
information — information about structural relationships of 
document components — in a PDF file. As a result, PDF' gave 
you a very accurate representation of document appearance, 
but no way to correlate text strings with paragraphs, say, or 
paragraphs with topics. (There is no easy way. for example, to 
reflow text inside a PDF file.) The PDSEdit biyer, building on 
new features in PDF 1,3. allows authoring processes to build a 
structure tree ? into PDF files, such that document content can 
be mapped to structure. The various methods of the PDSEdit 
Layer let you access, create, insert, remove, inspect, reorder* 
and otherwise manipulate nodes and leaves in the structure 
free and or traverse contents in a stniciured fashion. (A high- 
level Adobe official gave a talk not long ago in which he touted 
PDF's ability Lo act as a container for XML, Adolx 1 is known to 
be devoting a good deal of in house R&D to finding ways to 
make PDF and XML play together.) 

The PDSEdit Uyer offers some interesting, taming-edge 
functionality for developers interested in beefing up the 
metastmetural capabilities of PDF. Most plug-in developers wall 


never use tills layer, however, which is why it s not included in 
Fig, l and won't be discussed further here* 

Cutting Across Layers 

It may be possible for some plug-ins to implement all of their 
functionality by relying entirely on methods from just a single API 
layer; Ixit in general, this Is rarely the case. It’s more often the case 
dial a plug-in needs to draw on many types of functionality, using 
methods from more than one layer. Its not unusual, accordingly, to 
have to cal! on conversion routines that derive one type of “doe 
object" from another. Figure 2 shows some of the more commonly 
accessed doc object types and their associated conv ersion routines. 



Figure 2: How to get from one type nf “doc object J1 to another : 


In the example plug-in for this article (discussed in further 
detail below), we make use of methods from the AV biyer, the 
PD Layer, and PDFKdit. For example, we get the AVDtx* object 
with AVAppGetActiveDoc(), obtain an AV Page View using 
AVDocGetPageViewO, and get a PDPage from the page view 
using AVPageViewGetPageQ. Not all of these methods are 
shown in Figure 2, il would take many additional flow charts 
to show all methods. 

As I said at the outset, this is one of Adobe’s most complex 
APIs. Just finding your way around can lx* a challenge — with 
fir without flow chart diagrams. 

Notifications 

The Acrobat API implements a notification mechanism 
whereby plug-ins can register to receive notification whenever 
an event of interest occurs, For example, say your plug-in has a 
need lo know when a document has been opened, so it can 
traverse the document looking for resources of a particular kind. 
In that case, you’d probably want to register with 
AVAppRegisterNotificationO to receive AVDocDidOpen() 
notifications (which are broadcast whenever a document first 
opens). Over 80 different kinds of notifications are available, 
corresponding to an amazing variety of user actions and 
updates. In many cases, the notification will provide pointers to 
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diiLii which owy have changed as pari of the update action. In 
all cases, you can register a callback routine of your own to he 
executed whenever an event of interest occurs. 

For more information, see the section on Notifications in the 
Core API Oivn'iew. 

Enumeration 

It is often desirable to be able to enumerate through alt the 
components of a page or all the objects of a given type in a 
document, etc Fortunately, the API provides many enumeration 
methods that do this while also calling a custom callback 
procedure for each target object encountered. For example, 
when PDDocEnumFonts() is called. Acrobat enumerates all fonts 
used in the document and calls a user-specified callback for each 
font. (In AeroIxtt-API argot, a user callback in this situation is 
often called a monitor.) 

Exception Handung 

In general, API methods do not return error codes but 
instead raise exceptions when an error occurs. Developers can 
write liieir own exception handlers, since the default handler 
provided by the viewer app cannot always l>ack out of 
unfinished operations gracefully. Depending on the severity of 
the condition, your exception handler can either "fix* the 
problem and go on (thus absorbing the exception) or do 
whatever damage control is appropriate and then re-raise the 
exception so as to pass it up to the next exception handler in 
the stack. There is no definitive list of which of Acrobat's 1,100 
Ain methods raise exceptions and which do not. The safest 
policy is; When in doubt, assume that code am raise exceptions 
and surround it with handler calls. The idiom for doing this is: 

DURING 

avd = AVUocOpcnFrcmFi 1 p(jiKp. NULL, (char *)HULL); 

HANDLER 

avd = NULL: 

errorGoda = ERRORCQDE: 

AVA1 or i Note ("Error opening file’*); 

ENLU1ANULEX 

The DURING/HANDLER/END_HANDLER macros (defined in 
CorCalls.h ) expand to: 

ifdefine DURING I \ 

ACROjmp buf ASException: \ 

ACPushExc&ptionFrame f&ASException, \ 

(ACRcstnrrEnvi ronPron)ARer.torePlugInFrarae); \ 

If (SACROaetjmp(ASRxeeptinn)) I 

Adeline HANDLER JUtBSTOKK; I else I E RESTORE; 

tf define END HANDLER II 

If you want the host app to handle the exception, use 
the RERAISEQ macro. However, don't exit the current 
function while you're still inside an exception-hand led block 
of code. Instead, use E RETURN(x) to return gracefully (with 
k x’ as the return value) from inside a handler block. IL also 


goes without saying that you shouldn’t execute code Llmt 
might (itself) raise an exception, inside a handler, and you 
should avoid nesting handlers. 

For more information, l>e sure to read the section on 
exception handling in the Core API Oren ten\ 

HANDSHAKING AND INITIALIZATION 

Acrobat performs a special handshake with each plug-in 
at load rime, to give each plug-in a chance to register its 
name with the host, perform initializations! request 
notifications, install callbacks, and install an optional unload 
procedure. In order for handshaking to occur, the plug-in 
must implement die following method: 

ACCB] bool PUN ACfTR? FTKramishiike Ellus32 
handshakeVersion, void *hsDatfl) 

The ACCB1 macro expands to the pascal keyword (while 
the ACCB2 macro currently expands lo nothing). The hsData 
pointer w ill point to a data structure that currently looks like: 

typedef struct I 

AStlns32 handshakeVersion: // IN value: HANDSHAKE V020U 

ASA ton appNa&e: // IN value: Name of host app 

ASAtom extensionName : // OUT: Name of plug-in 

ASG.i 11 bar k exportHFTsCa iibac k: // OUT User mutjnc lo register any 

// HHTs this plug-m is providing 

ASCdllbiftk Unpar rRpplac^AndRegister Call back: //OUT: User routine 
// to import niher plug-in’s HtTs, mplaee HFT functions. 

// and register noli Heat ions 

ASCaliback initCallback; //OUT: User callback fordoing ini Is 
ASCallback unloadCailback: 

I PTHsrtdnhakftData VO2Q0; 
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The extensionName field muse he filled out with an ASAtom 
corresponding to the name of the plug-in, formatted according 
to ARCDJNamt\ where A BCD is a four-character "vendor" prefix 
while Name is the name of the plug-in. The AN Layer utility 
routine ASAtomFromString() can lie used to convert a string literal 
to an ASAtom. which is a hashed representation of the siring that 
Acrobat uses internally. 

The exportHFTsCallback field can contain NULL but can 
optionally be filled out with a user callback (which has lieen 
converted to an ASCallback) to a routine to call if die current 
plug-in is exporting any IIFTs, or Host Function tables, of its 
own, The MFT is an abstraction layer through which plug-ins 
and other processes can expose and/or access each other's 
functions. Several of the Adobe plug-ins that ship w ith Acrobat 
export their own IIFTs for other [dug-ins to use. For example, 
the Forms plug-in exports an ITFT containing pointers to 
functions that other plug-ins can use to traverse and/or 
manipulate form elements. 

Alter all plug-ins have loaded, the viewer (normally 
Aero bat) will cal! the at 11 back, if any, stored in the 
importReplaceAndRegisterCallback field. This callback is where 
you can import other plug-ins' IIFTs or register for notifications. 
(There is no need to import Acrobat's own HIT. since that's 
done automatically for you.) 

The initCallback should point to a user routine that 
performs any initializations that the plug-in needs done 
before it can function* For example, if the plug-in is going to 
install its own menu commands or toolbar buttons, this ts 
where it slioudl he done. 

The unloadCaflback should point to a routine that handles 
any memory-freeing or other uriload-related operations your 
plug-in may have. 


Compilation 

Acrobat is a !TC-nuiivc product, so there is no need to 
compile for a 6BK target unless you are compiling a Reader plug¬ 
in and want to include owners of older machines, (As mentioned 
earlier, there are significant limitations on what your plug-in can 
do if it is to use Reader as a host: and you must obtain a special 
key from Adobe.) You should plan on using a creator type of 
CARO and a filetype ofXTND for your plug-in. You can place it, 
or an alias to it, in Acrobat's Plug-Ins folder after linking. 

Access to Resources 

Beginning with version 2.1, Acrobat opens a plug-in's 
resource fork with read-only permissions. So don't plan cm using 
your resource fork for persistent storage. What's more, to use 
resources from your resource fork safely, you should plan on 
using the functions described in SafeRasources.h. That’s because 
plug-ins cannot assume that tlteir resources are located at the top 
of the resource chain. Calls like GetResourceO can fail 
unexpectedly unless plug-in resources are explicitly moved to the 
top of the chain . The resource calls in SafeResourcesT 
accomplish this. The functions described there are safe 


replacements lor all T<x>llx>x routines that call, or can call, 
GetResourceO because they move plug in resources to the top of 
the chain IxTore each call, then restore the resource chain to its 
original configuration after the call is finished. 

See Acrobat API Development (Tech Note No. S167) for 
more information. 

Example Plug-In: Aon Watermark 

'fhe example-code CW Pro 5 project for this article 
(available ai ftp://w , ww*macteclixom) illustrates many of the 
programming issues described in this article. The compiled plug¬ 
in, named AddWatennark* adds a light-gray text string (in 72- 
pt. Times-Roman) at a 45-degree angle across the current page, 
in response to an Acrobat menu command. For example 
purposes, 1 decided to use a Lcxl string of "Rough Draft." An 
example of the plug-in's output is shown in Figure 3, 
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figure J; Add Watermark applied to a page. 

(Note the words 'Rough })mft in gray.) 


The code for the plug-in comprises 260 tines of straight 
procedural C (in just five functions) in a file named 
AddWatermarkx. To compile the plug-in* you will need the 
Adobe SDK files PlMain.c and SafeResources.c in addition to 
AddWatermarkx. The project is compiled as a Shared library. 
There are no resource (,rsrc) files in the project. 

Gxle for the plug-in's handshake routine is shown in 
Listing 1. Tills is where we fill out various fields of the 
P!HandshakeData_V0200 structure so that the host will know 
who we are and what services we need. Note I ha I we use a 
fictitious “vendor prefix" of PLl-G on the plug-ins name. (This 
w ill not show up in the menu bar*) We do assign callbacks to 
two fields, but note that we don't simply stuff function pointers 
into the relevant fields. Rather, we use Lite AIM method 
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AS Call ba ckC reate Proto () to create properly formatted function I // «** lht tonMnte version dungs, add new -tfcr r branch here 

pointers to our MylnitQ and MyUnload{) procedures. return false; 


Listing 1: HHandshakcO 


PfllmufchakcO 


lllis is Llit plug in s handshake minim- See article for details. 

rat em ACCB1 ASBool ACCB2 PillandshiiktriUnsS?, handshakeVersion, 
void 'handshakeData) 

t 

if (handshakeVors ton = HANDSHAKER00) t 


// Cast handshakeData to tht- appropriate type 
PIHandshakeData_V0200 OiaData = 

C FlHand s h a keDa t a_VG 200 1 J h a ndsh a keDa ta; 


// Set the name you want Lu go by 

ha Da La >tixT<*nfdanNanie = 

ASAtomi’roniSc r ing("FLIKv AddWaterrcark"); 

ft If you export your own HPT, do mi here 

hsData >exportHFl’aCaIJbaek = NULL; 


// If you import HFTs, replace ftiridionaUty, 

// or want to register for itutifkations before 
// the user has a chance to do anything, do so here. 

hsDaia >lmpurtRcplar^AndRegisterCaliback — NOLL; 

ff Perform your ptug-in’s inittaliKtUon here 

hsData’MnitCaiXbaek = 

ASCallbackCreateProtcriPIInitProcType, MyTrUt); 

// Free memory or save siate on*t|Uir here 

haDala ^nloadCallback = 

ASCallbiiekCreuLePrototPTUnloadFrocType, My Unload); 


ft Dim 

return true; 


Cnde for Mylnitf) and MyUnload{) can be seen in Listing 2. 
The real purpose of Mylnitf) is to set up a custom menu 
command fertile plug-in. Notice that to do this we call a method 
named AVMenubarAcquireMenuByName(). Methods that have 
Acquire 1 in their names increment a reference count for the 
object returned. It's important that we later decrement the 
reference count by calling the appropriate Release method on 
the object. We do this at the end of Mylnit{). Since we created a 
new menu iLeui (storing it in the global variable 
Add Plug in Menu Item) in this routine, we later have to release ff as 
well. We do that in MyUnload(), 

Listing 2: MylnitQ and MyLInloadQ 

MylnitO and MyUnhxulO 

//This is tmr iniiiali&iiion callback mu Line. (It h optional.) 
ff If the ptug-ln can't Initialize for one reason or another, return 
ff false, Otherwise return true. 

ft Here, we set up our plug-in's own menu item in the Extensions menu. 

static ACERl ASBool ACCB2 Mylnitrivoid) 

t 

AVHenubar bar = AVAppGetMenubar(): 

AVMerni extensionsMnmi - 

AVMenubarAcquircMcnuRyNanififbar. “Extensions"); 

AridPluginHemiltenL = 
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AVtie n u I f emNew (" Ad d Wat ermn tk “. 

4 ‘FLUfi:AddWatFr&urh'\ HULL, true, 

NO_SHORTCUT, 0, NULL. gExtensionID)S 

AVMcfiuiteaSetEKecuteProc {Add F hig i nHonu Item. 
ASCailbackCreateFroto fAVExecnteProc * 
AddWatermarkComraarvd) * 

mil); 

AVKenu 11 emSe t Comp n t cEnab 1 edF roc {Ad dF 1 ug inMem; Item. 
ASCallbackCreaiuPt'OtoC AVCorapat©EnabledProe. 

AddltfaL g nnarkKnabled}, 

(void *)pdPemtEdit): 

AVMenuAddHenuIteaCesttmsioriuWemi. AddFluginMemil tetri. 0): 

//We did an Acquire (above)*so now Release: 

AVM e nuRe 1 eaa e( ex t en-s ions Menu): 

return true; 

I 

static ACCB1 ASBool ACCB2 Myllnload(vold) 

I 

// Remove and release any menus or menu Rems we t reated 
if {Add?)uginMenullest) I 

AVMonuitcmRemove(AddPluginMemiltem): 

AVMemil temRelease(AddFlugi nflemiTtetn); 

I 

return true: 

I 


The API routine AVMenultemSetComputeEnab!edProc() lets 
us specify a callback for determining -whether our plug-in's 
menu command should he ’greyed our under conditions 
when it would not make sense Lo [el the user invoke the plug¬ 
in. We use this routine to install our custom function 
AddWaternriarkEnahledt J* shown in Listing 3 The 
AddWatermarkEnabledt > function checks in see if a document 
is currently being viewed and if so, whether the document is 
edit-enabled. (Some POP documents are set up so that text 
cannot be selected or altered.) 11 there is no doc open, or ihe 
current doc is not edit-enabled, then it doesn't make sense to 
let the user try to use the plug-in for anything. Hence* we tell 
Acrobat to disable (grey out) the menu item. 

Listing 3: AddWatermarkEnabledO 

Ai ItlWaUTtiork linuhloX) 

This routine jursi determines whether cjr not our menu command should lx enabled 
a \ a Riven instant 

static ACCB1 ASBool ACCB? Add WatetinarkErta bled(void 
•permRequired) 

I 

AVDoe iivlkjc * AVAppCetAetiveDoc(}; 

PriPerms due Perms ■ 

PDI)ocCetP€rmissions(AVDpcGetPDDoc (svtJoc)); 

if (tavDoc) 
return false; 

return {(JWettasJpeniiRequired A donPenns): 
l 

The main action (creating Lhe watermark) takes place in 
AddWatermarkQommafidO, shown in Listing 4, You’ll notice that 
the entire body of lhe function is wrapped in exception-handler 
macros. We begin by fetching various doc and page objects* but 
since we use “get" (rather than “acquire") methods to obtain 


them, no reference counts are incremented and we don't need 
to Release those objects later. We do create or acquire other 
kinds of objects in this function, however, that do need to be 
released later. See if you on pick out what they are* 

The font we choose for our text (Times-Roman) happens 
to be one of the base-14 printer fonts that is guaranteed to 
be available on every machine that has Acrobat. We create 
the relevant font object for it so we can add that to the 
PDETexr object that will comprise our watermark. That text 
object also needs some graphics state info and a default 
transform matrix, (See my articles in the Sept* 1999 and 
March 2000 Mac lech for more information on transform 
matrices in PDF.) The graphics-state information has ro 
include a color-space designation and an ink color, as well 
as a miter limit, etc. (In truth, some of these values will be 
defaulted to reasonable values if we leave diem out.) We Ye 
using a greyscale color space and an ink color of 0.875 
(12.5% grey), specified as a Fixed number. 

Note that all oF the numbers in the transform matrix must 
be supplied as Fixed numbers. Since we want the text in our 
watermark to be rotated 45 degrees counterclockwise, we 
have To factor the sine and cosine of 15 degrees into the first 
lour positions of the matrix. (The first and fourth numbers 
have to be premukiplied by the cosine of the angle of 
rotation; ihe second number has to incorporate the sine of 
die rotation angle; and the third number has to incorporate 
the negated sine of the angle.) The text will begin drawing at 
a point one quarter of the way across the page horizontally 
and 50% of the way up the page vertically. The fifth and sixth 
coefficients of the transform matrix accomplish rhis 
translation for us. 


lasting 4: AddWatermarkComma i ldQ 

At UtWatefmarkCommamlC) 

Static ACCB I void ACCB2 AddWatennarkCooiiiiand (void ‘data) 

I 

ASInl32 mim: 

ASBool b; 
char huf |25fd ; 

AVtJoc avDoc: // Viewer's doc object 

PBPage pd Page: // reference lo m editable pgc ohjcei 

ASFlxedRcc I eropBox* // doc's crop box 

A V Page View pgViewj // current page in viewer 

FLlHCament pdeConrent: if container Inr page conieni 

PDEFont pdeFont; // reference in a I t ml used tm a page 

PBEFontA 1 1 r s pdftFontA i r m: H fortt aitriluilcs 

PDEText pdeText : // container for text 

Fi x©dM.s t r 3 x i_t?x iMat rix i // (rmsfurm matrix for text 

PDRGrapbicStste graphic©State: // graphic stcitc to appfy to operation 

PDEE1 ement pdeE 1 parent; // dement of page coiMCni 

F i x edMa t r ix e lemMa t rix i // dctltcn I HIM fix 

PDECoIorSpace pdeCulorSpare; //ColorSpacc 

AS In 132 1. j * n umF I p mn * miruH una: // for emit neril ion ol elements 


DURING 

// Get i hi currently displayed pape and its emphox 
avDoc = AVAppGetAc tiveOor (); 
pgView ^ AVDocGetPageView (avl)oc); 
pdPage * AVPageVi ewGet Page (pgView): 

PDPageGetCropftox {pdPuge. &cropBox); 

// Croatc Font object 

muniset (4 pdeFont Art rs * 0* sizeof (pdpFcintAu raj) ; 
pdeEotitAttrs. name J ASAtomFrmSt ring ("Times-Roman*); 
pdeFontAttrs. type - ASAtoinFrotiiSt riug('Typel w ); 
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pdeFont = FUKi^nlCceaietiipdoJ'ariLAurs* 
sizeot CpdeFontAttrs)* 

0 . 

255, 

0 . 

0, ASAtomNuU. 

0, 0. 0, 0); 

//The following code si ts up the default Graphic* State 

pdeCglorSpace - 

PDEColor SpaceCreateFromMame { ASAtotnF rgoStringf “DevlceGray’*)) ; 

mrjnfiPT (AgraphlcfiSrar.t*, 0, sizeof [PBEGraphicState)) ; 
grnph I csKs a t pi . wt rokffGolorSppc, space = 

graphIfsSlolc,fIllColorSp&c.space ~ pdeCaiorSpaee; 
graphiCtiSiate.flllColurSpee,vnlue.eolor[0] “ 
fixed SevenEighths; 

grsphicsState.miterLimit ~ fixedTen; 
graphicsState,flatness “ FixedQne; 
gr-i phi csS rare, 1 ineWidth = fixedOne; 

// Kill nui the text matrix, whic h determines the point si/r <d the font 

tuemset(^toxlMalrix, 0* L> ixcofftextent rlx)); //dear it 
textMatrix.a - HoatToFixedf. /Of * WA'MvMAKRAFTS IZE): 
textMatrix.b = textMatrix.a; // set font width and height 
textMatrix.e - EloatToFixed(-.7G7 * WATESMARX_?TSIZE}; 
textWaftix,d = textMatrix.a: 

textMatrix.h “ cropBox.right / 4: if x coord of start point 
textHaf rix,v = rropRox. top / 2; U y axird of stunpuini 

// create new text run 

pdeText * PtiKTextCreatel); 

PDETextAdd f pd eText. If text container to add to 

kPDETex t Run, // kPD ETcx iRun. k PD ETe *Oar 

0, ff index 

(IFnnB *)WATERMARK SIR, /Mextlu add 
s t rl en (WATERMARK .. _STR), // length of lexl 

pdef'art l, // font to apply to text 

&graphic:estate, slxeof (graphlesSUiLe). //graphic slate 
NULL, 0, // text state uud size of structure 

&t ext Matrix, ft transformation mam* for text 

NULL); //stroke matrix 

// Acquire the pngr content* as a PDEContcnt object 

pdeConietil “ PtiPagcAcqu 1 rePUEContent (pdPage, gExtensirmlD); 

ft insert text into page content 

PDEContenrAddElenitpdeContent, kFDEBeforeFirst. 

(FDEEleaie nt) pd eText); 


// Set the PDRGmtcm for the page 

b " PfJPagoSotPhEConcont (pdPage. gExten&ionlD) ; 

// remember to release all objects tbai werc created 

rum- PDFageReleosePDECantemTpdFage, gExtentilunlD) ; 

// Remember to release the objects we acquired or created 

PDEReleaiwt (FOlObJect.) pdeText); 

PDERolcase((PDEObjeet) pdRColorEpaco): 

FDKRele&soC (PDKObjccl) pdcFotitj; 

// Announce to the world that we changed the eoments 
// so the viewer will refresh the page 
PDPageNotifyContentsDidChange (pdPage); 

tf Mow somr exception-handler stuff, in case ol failure 

HANDLER 

AVAietrlNote(ASCetErrorStringUiKRORCODE. buf. 25b)): 
if (pdeText) 

PDERelease({PDEQbjeet) pdeText}; 
if (prioCoiorSpaee) 

POEReleaEcf(PDFObjeetI pdnColorSpneo); 
if (pdeFont) 

PDEReiease((PDEObj eet) pdeFon t ); 
num ^ 

PDPageRefeasePDEContent(pdFage f gExt ensionID); 

END _ HANOI.HR 
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Professional Software Developers 

Looking for career opportunities? 
Check out our website! 

Nationwide Service 
Employment Assistance 
Resume Help 
Marketability Assessment 
Never a fee 

Scientific Placement, Inc. 

800-231 -5920 800-757-9003 (Fax) 
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StoneTable 

You thought it was just a replacement 
for the List Manager ? 

We lied, it is much more ! 

Tired of always adding just one more featufe to your LDEF or 
table code ? What do you need in your table ? 

Pictures and Icons and Checkboxes ? 
adjustable columns or rows ? 

Titles tor columns or rows ? 

In-line editing of cell text ? 

More than 32K of data ? 

Color and styles ? 

Sorting ? 

More ?? 

How much longer does the list need to be to make it worth 
$200 of your time ? 

See just how long the list is for StoneTable. 

Make StoneTable part of your toolbox today ! 

Only $200.00 MasterCard & Visa accepted. 

StoneTablet Publishing 

More Info & demo Voice/FAX (503) 2S7’3424 
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The MacTech CD- 
ROM with Tl [INK 
Reference Ls the essen¬ 
tial reference resource 
for Macintosh 
programmers, 

'lias CD induties the 
THINK Reference 
personal database 
system and a wealth 
of Macintosh 
programming 
databases, featuring 
almost 170 issues of 
the journal of 
Macintosh 
programming - 
MacTecb Magazine. 

This release also 
features the THINK 
Reference Compiler, 
which allows you to 
compile HTML files 
into your own 
compact, searchable 
THINK Reference 
databases, and the 
THINK Reference 
Collector for building 
new Mac OS API 
Databases* 


CD-ROM 


with THINK Reference 


The rest is pretty straightforward. We acquire the page 
contents as a PDEContent object, add our text element to the 
contents list (specifying kPDEBeforeFirst. to lie sure the 
watermark text is the first thing drawn on the page, making 
it draw 1 “in back of” all other page elements), set the page's 
content to the new content list, then release the page 
contents object and notify the host app that the page has 
changed (so it will be redrawn). 

Because PDFs graphics model uses opaque ink (at least 
in version 4.0 of Acrobat), objects draw on top of each other 
in the order they’re laid down. Fortunately, the API lets us 
add new objects to either end of the “draw IistT Thus, we can 
draw our watermark text either on top of all other items 
(partially obscuring other page elements) or underneath all 
other items (in which case the watermark itself may be 
partially obscured). The disadvantage of drawing the 
watermark first is that if the page is particularly "busy" or has 
some very large graphics, the watermark may be mostly 
obscured. One workaround for this is to use a watermark that 
forms a tiled pattern across the page, with small individual 
elements. (PDF does allow tiled vector graphics, incidentally.) 
Another tactic is simply to draw the watermark on top of 
other page elements, but make it less conspicuous by (for 
example) drawing outlined text rather than solid-filled text. 

There are many ways in which the Add Water mark plug-in 
could be improved. Now that you have the basic code for 
adding text to a page, maybe you c an Implement some of those 
enhancements yourself. (If you do* please send me a copy.) 

Conclusion 

PDF is a complex and sophisticated document format. Nor 
surprisingly, the Acrobat plug-in API is correspondingly 
complex and sophisticated. In fact, with 1,100 methods 
(covered in a reference document that’s almost 3*000 pages 
tong), it is aiguably Adobe's most elaborate API — outdoing 
even the Photoshop plug-in API for sheer intricacy. One well- 
known Ac robat plug-in developer routinely tells clients that to 
accomplish any non-irivial task using the Acrobat API can take 
an experienced programmer (ix\. one who is experienced at 
C/C++ development, but new to the Acrobat API) a minimum 
of six months. That may be overstating it a bit. But you can 
probably appreciate the fact that Acrobat plug-in development 
is not something you become adept at in a weekend. The API 
is rich lo the point of being unwieldy at times (and suffers 
from subtle architectural shortcomings, which only become 
obvious after you've spent many hours working with it). But 
although the Acrobat API lacks the elegance of. say, the After 
Effects API and fails, for the most part, to make a complex 
document format (PDF) easy to understand and work with, it 
does expose an amazingly diverse set of capabilities to 
programmers who might need to extend Acrobat's already 
impressive arsenal of PDF editing and annotation Lools. And 
that, in and of itself is saying quite a lot. IBS 
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Yellow Dog Linux Champion Server™ 

by Terra Soft Solutions, Inc. 

Dedicated to Apple Computer, Terra Soft Solutions maintains the largest 
and most experienced PowerPC Linux development staff in the world. 
Enjoy this mature, proven, and professional Linux distribution. 

In addition to the expected Linux applications and utilities 
Yellow Dog now includes Mac-On-Linux which runs 
the Mac OS inside of Linux at near native speeds, and 
"yupf”, our famous automated system update utility. 


Available on 3 CDs or pre-installed on hard drives. 
Includes bootable Install & Rescue CDs and all source RPMs. 

60 days installation support available. 
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TECH HOME™ 


By Neil Ticktin, Publisher, MacTecb Magazine 


Home Automation: 
The Geek’s Holy Grail 


STAR TREK 


OK... f admit it. I’m one of those closet 
geeks that looks forward to the day of having 
“Star Trek” level of control of my 
surroundings. And, given what we saw on 
die last MacTecb reader survey, most of you 
fed the same way I do (actually, nearly 80% 
of you), 

Home Automation (HA for short) has 
long been die holy grail for techies of all 
types. Today, there are some great options, 
and things are looking even better all the 
lime. In looking at Macd^ased HA, a whole 
new world has opened up. Some folks have 
been at this kind of stuff for years — at a 
variety of levels. Bui, if you haven't gotten 
started, now is a great time to do so. 

With this article, we're going to take an 
initial, and broad, kx>k at HA and how you 
can have the 'home of tomorrow" today. Of 
course, the centerpiece of diis is,, your Mac. 
One caveat up front: this article is so broad 
dial if you aren't interested in [lie part you are 
reading... just skip to die next part, it’ll lie 
about something different. 

What do you want to accomplish? 

First, you need to determine what you 
want to accomplish with HA. This may seem 
like a trivial question — but ifs actually quite 
difficult. And, you really, really need to 
determine the impact of SAP H Spouse 
Approval Factor" in what you are doing. 

For example, our electrician told my 
wife stories about a house that seemed 


straight out of AmityviUe Horror or Poltergeist. There were some 
problems with the automated lights that sent random signals,,, lights 
would literally turn on and off in an almost haunted manner. This noi 
only concerned me, but 1 got some stem looks from my wife 
(understandably). 

Bering conservat ive (and realistic), 1 decided to take an approach 
dial accomplished IIA. but was designed in a way dial if dungs didnl 
work the way we wanted, we could revert to conventional (non- 
automated) methods, 'Ibis not only gave me a lot of flexibility in my 
own comfort level but drastically increased the SAP And, increasing 
SAF is always a good thing 

New Construction or Retrofit? 

Implementing your goals prompts a series of other questions. 
Ihe biggest of which is whether you are building a new 
environment, or do you need to retrofit the existing environment? 
Tins is a huge question, and it will govern many of the 
implementation decisions dial you need to make. 

Let’s take an example that we’re all more familiar with. Let’s say 
that you want network access everywhere in your house. With new 
construction, you may want to run CAT 5 or better cabling 
everywhere you ran diink of, But, if you don’t have access to the 
inside of your walls, maybe wireless would work letter. 

Likewise, if you want to control lighting... do you want to go 
over existing power lines? Or t can you hard wire control lines to 
switches for greater reliability? Again, ii comes clown to whether you 
have access to the innards of your walls/ceilings. 

Let's Get Down to rr 

Enough pre amble, what are we trying to accomplish here? We 
embarked on a fairly ambitious project that combined tactics of new 
construction with retrofit. The goals were as follows... 

* Computer Network 

* Environmental Network 

* Entertainment Network 


Neil is the Publisher of MacTecb Magazine and the CEO of Xplain Corporation. Hex been around die Mac developer 
community for many years — with his first Mac program shipping in 1985, 
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Computer Networks 

MacTech has had some recent coverage of networks, so 
well keep this part really brief. My believe is that, if you are like 
me, you want to have a relatively serious network in place at 
home... not only for the needs of today, but tomorrow as well. 
This may not Lie just for your home office, but where your kids 
might play — or In a guest room. 

No matter how you slice it, build your network light. Thai 
means modularity. If you can, run Category 5e or letter wire in the 
walls to a central distribution point. At that palm use a patch panel. 
From the patch panel, use short patch cables to take you to a hub. 
If your traffic warrants it, take it Lo a sw itch instead, either now , or 
in tiie future, lastly, your Internet connection will tie into tire 
network giving your entire house connectivity with a single 
connection. Products like Lhe MacScnse XRouLcr (available from 
Devdojx-T Dcjxh chttp ://www. devdepot, com>} can help you share a 
single IP throughout the house w ith DHCP and other features. 

HomeLine from Farallon 

For those of you dealing with retrofitting your house with a 
computer network, you may want to consider Para!Ion’s HometJNE 
(<http;//vww,farallonxom/>). Some people would call this the Ethernet 
version of PhoneNet. Others iniglit call it indoor DSL, Whatever you 
call it, basically, you can run at a megabit (e.g., I8x faster than a 56K 
modem), but over your existing phone wires (without any wiring 
modifications). And, die liest part Is that these existing phone lines 
can continue to be used simultaneously for both voice and 
network,., just like DSL. If you are looking to share a single Internet 
connection, will tout having lo run new wires, it's a good solution. 

What about wireless? 

The first question is wired or wireless? The answer: both. In our 
house 1 , we have wired connections for desktop computers, while die 
mobile machines have wireless access. 'this is done with die 
AirPoifs big brother — the Lucent WavelAN product line (which is 
now called ORINOCO), Because Uicy are based on the 802,11 
standard, the Lucent bridge works very well w ith the AirPoit card in 
my PowerBook. So well in kid that wireless is the only connection 
I use on my PowerIkx)k... even when Fm sitting at my desk. 

The reason that we have both wired and wireless is for division 
of traffic, 1 want to keep our wireless network working as fast as 
possible - so by hardwiring those that are easy to, 1 keep machines 
olT die wireless LAN. 

For more information on wireless networking, .see MacTech 
issues from January 2000 and December, 1999 
<http;//www.rnadedi.com>. 

The Tools to use 

For this article, die important tiling alx>uL your wired network 
is tile UxjLs and products that you can use. There are a lot of quality 
brands out die re for cabling, connectors, patch panels, and more. A 
few to call out are Levitt>n (< http:/ /WWW. leviton.C0ITl/>), CliannclPlus 
(<http://www.charmelpbs.com>) and Belkin (<http://www.belkin.conn>). 
Levitan has some really nice modular connectors that match die 
coloring of the other plates in your house.,, they are the inventors 
of the “Decora” style. 


Channel Pi us has some excellent integration with entertainment 
networks (e.g. T coax). Move on ChannelPlus at die end of this article. 
For this project, we primarily used Belkin products. They 
have a variety of patch panels, mounting brackets, and wall 
plate/jack combinations, I found their products to he very 
easy to work with. There are two things that you should 
know r — their wall plate products do not come in a wide 
variety of colors, so watch out for the SAF here. Also, make 
sure to use the products that ' require tools'' — they are much 
easier to deal with. 

One of the nicest wiring products that Belkin has is their 
"snagless 11 10/100BASET cables. These cables have “snagless 
molded strain relief which is a fancy way of saying that they 
will help you prevent breaking the connectors at the end of 
the cables. The design works well — I haven't broken one yet. 



Belkin Snagless Cables, 

For any network waring, you will want to spend the 
money and get yourself a good punch down look With about 
1/2 a mile of cable in my house, and nearly 100 connections, 
1 can confirm that iris well worth it. This tool allows you to 
easily connect wires Lo a punch down block, die back of a 
patch panel, and even certain types of modular connectors, 
Furthermore f it will allow you to cut (or trim) wires in the 
same action as you are punching it down. Punch down tools 
are available from any phone equipment vendor. 

A must have in your tool box is what is commonly 
referred to as a "fox and hound", This is for identifing cables. 
You've got all this cable running all over the house, now you 
need a way to figure out what goes where. You can try 
labeling ahead of time, but that can be a hassle (or you might 
jUiSi forget to do it like me). We used lhe 701K kit from 
Progressive Electronics. ( <http://www,progressive-inc,com/>). 

You take a “tone generator" and connect it to one of the 
cable and then pass a “Inductive Amplifier 11 over the bundles 
at your termination point 
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Progressive Electmmcs 70IK kit. 


New Construction 

If you arc doing a project that has new construction, you 
should setiously consider a full “wiring system". We won't go into 
those here, but you should check out HomeStar from Lucent, 
LonWorks from lev icon, On conics InHouse, and OnQ Technologies. 
These give you a very simple way to combine all of your assorted 
wiring needs through one system. They are an excellent choice for 
new construction, but yoti wouldn’t want to deal with it fora retrofit 
— you'd \xi opening every wall in the house. 

ENVIROMMENT (jON'I'ROI. Network 

The first tiling that probably comes to mind when you hear 
“environment control" is heating and air conditioning. While this 
is part of it. there’s a lot more to controlling your house. What 
we’re going to focus on is retrofitting a house with “PowerLine 
Carrier" or X-10 protocol devices, and controlling them with your 
Mac. Realize that you can do PowerLine Carrier with new 
construction, hut, you should first look at one of the wiring 
systems before doing this type of setup. 

X-10 is the trademark name that many people know it by — 
bur PowerLine Carrier is what the protocol is really called. Levitan, 
one of the leaders in the industry, calls their product line “Decora 
Home Control" or DUG. Well use the names DHC, X-10 and 
PowerLine Carrier interchangeably. If you remember X-10 from 
the HSR days, forget it. Today, PowerLine Carrier is a whole 
different ball game. When the patent expired on tills technology 
some years back, the entire market was opened up to 
competition... and today, there's a whole array of X-10 
compatible devices from a variety of vendors. 

Let’s take a look at how this protocol works... 

The PowerLine Carrier Network 

PowerLine Carrier devices work together as a communications 
network. Programmers, controllers, and computer interfaces are the 
transmitters in this network. They are installed at locations in the 
home convenient for their designated use. All transmitters send a 
unique axled command signal throughout the home's existing AC 
wiring, which links the entire network together. PowerLine Carrier 
switch, fixture and receptacle (outlet) modules, which act as 
receivers in the network, are installed in place of standard switches, 
outlets and dimmers at key locations throughout die home. 


The PowerLine Carrier Address 

At the time of installation, each receiver is set to a specific 
system address, which consists of one letter from A-P (16 
possibilities) and one number from 1-16. Typical addresses are A- 
4, C-6, J 12. There are 2% letter-number combinations available 
for use as system addresses. The system address is set at each 
receiver by turning a dial to the desired letter, or house axle, and 
another dial to the desired number, or number code. On some 
devices (e.g., wall switches), the code wheels are hidden (e.g., 
behind the switch plate). 

The PowerLine Carrier Command Signal 

When activated, transmitters send a 3-volt, 121 kHz series of 
pulses, called die “command signal", at die zero crossing of die 60 
cycle AC power curve (see figure). Transmitters then repeat the 
command a second time for added assurance. 



PmvrUne Carrier Command Signal. 


The command signal contains a specific address axle and a 
performance function axle (on, off, dim, brighten, all lights on, 
all off, etc:. .). Transmitters can send command signals to all or just 
a selected group of system addresses, depending on die particular 
model. Marty wall-mounted controllers will retain aimmand signal 
transmission if a command from another controller is in progress 
on the AC power lines. When the line Incomes clear, the wall 
units will then transmit. 

Receivers monitor the AC power tine constantly, “listening" lor 
a command signal. When one. or a group of receivers "hears" its 
specific address, it responds by performing the designated dimming 
or switching function. The command signal can travel a considerable 
distance and still activate a receiver, if no electrical loads generating 
interference ate present to dissipate the signal strength. No more 
than 4 transmitters should be on [he same AC branch circuit, since 
dlls can reduce signal strength considerably. 

Quality of Products — 

Save yourself some grid and plan ahead 

Every home has some electrical “noise" on the AC lines that 
can cause interference with command signal reception. Know 
this up front. And, to some extent, working with PowerLine 
products can be more of an an than a science. However, there 
are several things that you can do to work in your favor... and 
keep your headaches to a minimum. 

First, buy quality hardware. We saw several different vendors of 
X-10 and PowerLine products. You can tell the difference with the 
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quality < mcs once you have them in yo^ir hands, We used the neuter 
Leviton switches primarily — and were very pleased with nol only 
the products performance, but the look and feel as well. Make sure 
you get lire newer Leviton ones (check the leviton web site for the 
latest versions). Some resellers will try to sell you the older versions, 
which ;ire nor as good. 

Leviton switches use a special circuit called “Intellisense” (gated 
automatic gain control). Intdlisease Ls supposed to provide DHC 
receivers with outstanding noise immunity during the critical “zero 
crossing” interval of the 60 Hz sine wave. As far as we can tell, it 
works great — and the switches were very gtxxl at avoiding noise 
that we knew to be on die lines. 

There are other problems to avoid as well For example, if 
your house is larger than 2000 sq. ft. or so, you want to use a 
bridge/amplifier. Let me explain. Houses are wired in two 
"phases". Almost like two zones on a network. In a smaller house* 
the signals may bleed over the phases well enough, but you are 
still likely to need a low cost coupler, In a larger place, you need 
to install a bridge/amplifier or coupler/repeater. We used the 
leviton 6201 Coupler/Repeater, and it performed wonderfully, in 
fact, there was such a noticeable difference, you should consider 
putting one in regardless of the size of your house. The only 
problem is the cost, they are one of the pridest items in an 
PowerLine installation lisi at as much as $200. 

You also want to consider putting in a panel mounted surge 
protector. This will not only protect your electronics internally* but 
it w ill help with some of the noise as well. Here, we used the Leviton 
511203R You may also want to consider a noise filter or block that 
Ls installed at your breaker box. We didn't do tills, but many people 
wall find it necessary, 

One thing to realize is I hat the singe protectors you may use in 
your house (eg,, with your computer) may cause problems with 
PowerLine signals, Why? They filter noise, What Is a PowerLine 
signal? Noise, In fart, the lietter your suige protector, the more likely 
it is to cause problems. 

And. there are other culprits that can cause noise. For example* 
instant on TVs (which are basically all IVs today), refrigerators, air 
conditioners, low voltage lighting (e.g., Malibu type lights as well as 
indoor low voltage), and more. What can you do? If you suspect 
anything, put in line and plug-in noise filters. We used a lot of the 
Leviton 6288 and it worked great and is cost effective. 



Levtion Hug-in NoLw Filter (#6288). 


Computer Interfaces 

One big question that probably comes to mind Ls how does die 
computer talk to die PowerLine devices? Its pretty easy actually. 
Typically* people are using older Mites. One of our primary 
machines is an I.G 111... remember those? You Like a serial output 
from die camputer (e.g., die modem port) and plug it in with an 
adapter cable to an interface We used the IBM Home Director. Be 
forewarned though, most people have complaints about almost 
every one of the interfaces out there. For as, we tried multiple Home 
Directors* yet still see phantom messages come across the log diat 
may or may not be there. 

We have heard fairly good ihings uhout the LynX-10 by Marriek 
(<http://www,marrickltdcom/>). Hie best known issue with it Ls dial it 
may have difficulty keeping track of dim settings going over the 
network. So, you would have to code your software to compensate 
for tins — something that’s a gcxx! idea anyway. 

While some folks consider the CP-290 interface to be limited 
and even obsolete, the people that we spoke to called it "undeniably 
die most reliable X-10 interface”. Someihing worth considering. 

There are a variety of interfaces from the slew of mail order 
companies that serve the HA community. See the end of the 
article for some links. 

Debugging Too ls 

OK, so it wouldn’t lx* a MacXech article unless we spoke alrout 
debugging. <g> The hands down winner here is a product called 
the “PowerLine Signal Analyzer 11 (PLSA) liy Monterey Instruments 
(760941-3666). Hie product is pricey ($349), and it lias an interface 
djaL it takes some getting used to h but if you are serious about 
PowerLine* get diis product — you'll save yourself a lot of grief 

The PLSA will allow you to do several tilings. First, it allows 
you to look at raw codes. So. when we couldn’t figure out what 
was going on with some phantom messages, we could instantly 
tell with the PLSA that they were phantom. We were also able 
to quite easily determine the before and alter differences of the 
a >u pier/re pea ter i nsta Hat inn. 

Many sources have told us dial die signal slrengdi of a 
PowerLine signal should lie Ixrtween 100 and 2(K) millivolts. Even if 
the device is rated at as little as 50 millivolts, you should still look to 
have at least 100 inv to give you extra buffer. On a similar note* 
typically 100mV of noise or less is OK, The PLSA will help you 
identify both of these easily. 

In short, you can do die following with this tool. Code 
identification, signal strength monitoring, noise metering, signal 
dissection and recording history. 

The manual will give you an excellent understanding of how 
code transmission theory works. \i will educate you on a numlxjr of 
other important areas. If you get this product — read the manual 
Pm serious. You'll spend 10 minutes reading the entire thing* cover 
to cover, and you'll save yourself hours. 

Enough Background, Let's Do Someihing 

Enough theory* what can we do with this stuff. ITie two 
easiest things are controlling lights and electricity... and 
controlling irrigation. 
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Lighting 

To rnL% controlling lights is a big enough item, and worth doing. 
We've used a combination of PowerLine products and conventional 
motion detection to do ihis. Why is lighting such a big deal? It comes 
down to a couple of things... convenience and security. 

When you have computerized control of the lighting, you 
can do some nice things. For example, 1 have our front porch 
and pilaster lights sei up to go on automatically. The computer 
calculates Lite sunset based on our area each day. The lights are 
set up to go on a random number of minutes after the sunset 
This not only gives us the convenience of automated lighting, 
hut the security of it looking like someone is home. The 
switched lights are all controlled by conventional light switches, 
lint just use ones that receive Powerline signals. We used the 
Leviton 16383 (make sure you don l confuse these with the older 
6383). These are very nice looking, solid feeling switches. And, 
while they look similar to a standard Decora rocker switch, they 
operate a bit differently. To turn on the light, you tap the top 
half. Oil? Tap the bottom half. Dimming? No problem. Press and 
hold the top or bottom half. The switch remembers the last dim 
setting and uses that for when yon ‘'tap" it on. 



leviton DHCSimtch (*16383) 



These lights have an interesting feature. let's say that the txxle 
for this light is FI. When the motion activation happens, the 
transmitter will not only turn on the light, but can also send on 
signals to F2-F5 depending on the switch settings. We utilized this 
feature to install two sensors for one corner light. The firsl sensor 
can send a signal to the second sensor to turn the light on. There’s 
a short delay when it does this, but it works well enough. 

For our house, we have one motion sensor on each corner of 
the front of the garage door. So, it stands to reason that if Ixjlh 
sensors are triggered simultaneously (or nearly simultaneously), a 
car is probably pulling into the garage. Now, in the really cool 
category, we wanted to have the hall lights inside turn on. By 
monitoring the time cadi motion detector was turned on, you can 
have a script that sends that signal to the hall light wall switches. 
Well revisit this to write a script to accomplish this. 

Another example is .something that Michael Ferguson (well 
known in the Mac 11A community), has running in his home, fie 
can ask the computer for the whereabouts of others in his house 
arc. Based on educated guesses, the computer will give a “most 
likely" response to him For Michael, who lives on a fairly large 
property, this is really useful. 


You can also do a “three way* switch if you use the 
Leviton MSOOR-l remote (or slave) in conjunction with the 
Leviton 16383. Now, if you are completely anal like me, it 
actually may annoy you to see ihe light off, hut one of the 3* 
way switches in the wrong position (e.g. T it looks like ii s 
turned on). No worries. Because of this “tap" on/off type 
action, lire switch always returns to the neutral position. 

Motion Activated Powerline Signals 

If you ask someone in law enforcement, they will tell you that 
one of the most effective crime deterrents you can do is motion 
activated lighting. Now. you can use convention a) motion 
detection, but one thing that PowerLine will do for you is actually 
log the activity, not to mention allow you to control that lighting. 

We used a series of Leviton 6417 “passive infrared 
transmitters”. For some reason, these only came in a chocolate 
brown, so we had to spray paint them to match the coloring of the 
house. The sensors can “see* 110° for up to 40 feet; and have 
settings for sensitivity and darkness. 


Conventional Motion Activated Switches 

Sometimes, you don't need the computer to do everything. For 
example, there were some places like the garage that we didn't need 
computer count>1 on, but wanted there lo l>e motion<lctected 
lighting. In this ease, you can use something like the Leviton 16775 
"Decora Wall Switch Occupancy Sensor", Like the 6417, this is an 
infrared sensor, but this one Ills in die place dial a Decora wall 
switch normally would. You can set the switch to auto, off and on, 
This switch is a great solution if you don't need PowerLine control 

For us, ids been the sohnion lo the argument “whyd you leave 
the garage light on all night". Remember, SAP is very important, (Yes, 
l was usually the culprit.) 

Electrical Outlets and Lamp Modules 

There are so many devices that can he controlled well 
if you can just control their plug. Here, you have two basic 
options: a plug in lamp or appliance module, and a hard¬ 
wired outlet. We used both. 

For the outlet, we used the Leviton 6280 Duplex Wall 
Receptacle. We used these for all of the low voltage lighting 
(with plug-in noise filters) that include “up lights" for trees, 
and other decorative lights. 

For the pilasters that are in front of our house, they have 
electrical outlets as well. Because they are in front of the house, we 
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didn't want them tn always lx; on, So, we used the 6280 to mniml 
the |X>wer from the computer — that way, they are usually off 
unless we want them on for a specific reason (e.g,, holiday lighting). 

Lamp and Appliance modules can lie used for all kinds of 
things ranging from a light to a coffee maker. It's just up to 
your imagination. 

Telephone Transponder 

One minor aside, you Gin use, without a computer, a 
“telephone transponder" to control ilungs. Persomilly, 1 Found that 1 
was able to do most everything l wanted with the computer. One 
good u.se for the Telephone Tratisjxmder is to access scripts on your 
system from your touch rone phone. We used the Ijeviion 6325 
when we wanted lilts type of interface. 

Irrigation 

If anything other than lights needs to be automated, il's 
sprinklers. Sprinklers are one of those tilings that, when done right, 
still need constant tweaking. It Ls possible to build a “jikxIcT that will 
allow you to control ynur sprinklers w ith good results. For example, 
let's sciy that a nr >n raining, Winter schedule ate half the days and 
two thirds the duration when compared to the maximum watering 
schedule (Summer). You can see how you can build a model that 
suits your individual .situation. 

However, unlike lights, there are some worries alxmt 
com lolling sprinklera. For example, what liapjxus if your system 
goes hay wire or the computer crashes? Will the sprinklers he on all 
day? What if it rains? What if it rains a lot? 

The solution is to get a product that really understands hih 


sprinklers and PowerLine. Enter the IRKMASTFR-Pro from RCI 
Automation. These units come in a 4 and H zone model. You can 
use as many units as you want in a system provided that you have 
enough available house codes. Any time a station is turned on. it will 
turn oft automatically after HO minutes, this is your safeguard against 
problem commands. 

The unit can lx* turned on manually from the lx>x itself (e.g., in 
your garage). And. you can hook in a min sensor (they use the Mini- 
Clik II Rain Sensor). Hain sensors can bloc k watering until the sensor 
lias dried out. More specifically, the system goes into a "suspend" 
mode when the sense >r delects rain. Tlie IRRMASTFR-Pto then sends 
a unit 10 X-10 ON command to your home automation controller so 
you are informed of the ram condition and that the system is in the 
suspend mtxle, The IRRMASTER-Pio continues to send a unit 10 X- 
10 ON command every 24 hours to keep y< >u informed that the 
system is still in tlie suspend mode. When the discs in the rain sensor 
dry out, the circuit opens again arid the IRRMANTFR-Pro sends a unit 
10 X-I0 off signal to your home automation controller to inform you 
that tlie suspend mode is over. 

Tlie sensor Gin lv adjusted to different quantities of rain. So, if 
you want to get up to I t" of rain liefore turning off the sprinklers, 
you can make that adjustment (anywhere' from 1/8" up to a full 
inch). Since the hygroscopic discs in die sensor dry at approximately 
the same rate as turf, the sensor and your grass w ill roughly jxtndlel 
each other, as you would want them to. 

In addition, if you warn to shut the sprinklers off for 72 
hours, you can send Lhe IRRMASTER-Pro a unit 9 X ID OFF. The 
suspend mode will automatically end 72 hours later, or you can 
immediately end the suspend mode by sending the 
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[KKMAvSTER-Pro a unit 9 X-10 ON command* These fund ions 
can also be performed manually by pressing the Enable/DLsable 
button on the front of the IRRMASTER-Pro. The green LTD will 
be lit when the system is enabled. These functions are 
independent of the rain sensor functions. 

One planning tip — you'll need a contiguous block of 
Powerline addresses tor the irrigation system* In our case, we need 
two bill house axles. You should plan on one house axle per 
IRRM ASTER* So. IxTore installing the JRRMASTER, we had to do a 
bunch of system rearrangement of all the other Powerline devices 
to dear the space needed 

PCI can be readied at <http://www.rciautomation.com/> or 
6194*57^268. 


ADB I/O From BffHivf 

While we didn’t get a chance to experiment with this product 
first hand, it definitely is something you should know about. ADB 
I/O is a Mac peripheral that allows you to control electronic 
devices and read data from sensors. You can control it via 
AppleScript (and therefore home automation software), or by 
writing your own code. There are some commands iliai you can 
do with the bundled software as well. As the dexumentation says* 
rite possible applications of ADD I/O are almost endless, but to list 
just a few: Computer controlled science experiments in sehtxils or 
at science lairs; control c>r electronic devices in your home; access 
com iv >1 in office buildings; const nut i cm of complete weather 
stations by attaching wind, temperature, humidity, light sensors 
and barometric sensors. *See mote info at Bee Hive Technologies 
Inc., <http://www,bzzzzzz*com/>. 

G)MPITFR CiONTROU** Till; SOFTWARE 

Wve s|x j nt all this time talking about the network and the 
hardware, now its time for the software. On the Macintosh* them 
are three main pieces of software for controlling X 10: XTension by 
Sand Hill Engineering, Mouse House, and Thinking Home by 
Always 'blinking. We took a Ux>k ai XTension and Thinking Home. 

Pirsl off, you should know that these are both great products, 
lliey ve approadxd tilings differently and have different heritages. 
You really couldn't go wrong with either of them. Were going to 
dive in here and just show you how die products work* 

Xtfnmqn 2-3*8 

XTension is a fairly mature piece of software, especially in 
home automation industry terms, XTension was written by Michael 
Feigtison, an engineer with a background in control systems. When 
you first open XTension, you am presented with a variety of 
windows; a master list of units, scheduled events, and a log. 



Xl'emum Overview 


However, there are oilier excellent ways to view information. 
For example, a graphical view' of your house showing assorted icons 
representing XTension controlled items in your house* You do tills 
by simply creating a PICT, editing a new "View" in XTension, and 
then positioning the assorted items throughout the map. And, you 
can control items by clicking on tire views. 

As the status of items changes, the map is updated For 
example, in the figure* you'll see the sprinklers on, assorted lights, 
and an icon that represents whether the sun is up. 

Liter in the article, well talk about how you can view tills map 
on a television channel throughout your house. 



XTenskm House Map 


One of the first things that you'll want to do is set up the 
units. This is incredibly simple to do, it i*s just a matter of filling 
out this dialog* 
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XTrnsim Editing a Unit 


You may also want to citrate events at certain times, That is also 
easy, you just till out lliis dialog lx»x. 



XTensum Editing an Emit 

There are some tilings that are a "mast dtT when using Home 
Automation software. One of those is action based on the sunrise or 
sunset. Based on your location, XTension calculates the sunrise and 
sunset times each day, Why is tills important Look around your 
neighlx jritorxL If it's like mine, you II see a huge variety of times tliat 
neighbors outside limits are on... all making their best guess at 
darkness. Now, you ran do it with some reality. >. still adding in 
some randomization to make it look like you are home. 
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Preference 


G#nrral \ 0 ?mfn»un iwt IWS J Logging 

0 Auto save scripts to TEXT 

Sunrise: 558AM 

□ Auto sort lists 

Sunset: 739 PM 

0 no duplicate addresses 


□ Monitor only 

□ Lock Windows 

0 Backup database 

f Password.., ) 

Every [ 60 | minutes 


□ Do write current time 


□ Save script context 

Return key is: 

□ Execute text unit scripts 

®ed»t O toggle 

| Cancel J | 

OK ] 


XTcnsum Preferences (Sunrise/Sunset) 


Writing a “Suriser script can be incredibly trivial. In fact. 
XTension has it built in tu just run the script called "Sunset” at 
the appropriate time. 



XTension Sunset Script 


Now, one of the best features of XTension is its 
incredibly strong AppleScript integration. Not only can 
XTension run AppleScripts, you can also edit them from 
directly inside the application. If you are working on a 
machine with limited CPU power, this is incredibly useful. 

AppleScript is really built-in to XTension. For example, 
even the communication between the serial port manager 
and the “main process'" is via AppleEvents, As MacTech 
readers know-, this makes it very easy for Sand T Till to add 
new features, which often result in passing those events to a 
‘monitor or 'targeted’ copy of XTension. 

You may remeinlxir from earlier in the article. w r e have 
two motion sensors on the garage: one ar each corner. The 
below script is activated when an ON message is received by 
Motion: Garage \¥. It checks how long it has been since 
Motion: Garage H went on and if they are w ithin 5 seconds of 
each other, turns on the hall light inside the house, A similar 
script is set up for Motion: Garage E checking the time delta 
for Motion: Garage W and turning on the light us necessary. 


The trick here is that we re using the leviton 6417 passive 
infrared transmitters. These are hooked directly to the flood 
lights so Lliat there is no delay in them turning on, (There are 
slight delays in sending PowerlJne signals, but they are less 
than a second generally ) In this way, they act like non- 
PowerLine motion detector lights. But, we want to know when 
the lights are going on T so we ask the 6417 to output a 
"phantom" code. In this case, it’s the address of the 6417 (PI) 
plus U.. in other words, F2. To capitalize on this, we define a 
“phantom" unit, which is K2. It doesn't represent anything 
physical, but it does allow us to have the below script. 



XTtwsioit Editing a Script 

In my mind, this is in the "hack" category, but you can do 
"variables” in XTension as well. The trick typically used is to create 
additional phantom units (ones that have no physical 
representation). Then you can store values in them. For example, 
the lx4ow script keeps track of rainfall 


Edit Script 


global scrip! Daily 


- - 7hK serpf *> jll Hu its 


set value of ^Ral r>4" ta value of 

set value of “RaJ n3~ to value of RafcnZ' 

set value of “RaiftZ" to value if “Ruin Yesterday" 

set value of “Ftai n Yesterday to val ue of “Daily Ral nfall 

set va! ue of "Last 4deys" to (value of "Rai n4") * (value of "Rai h3“> * 
(value of "FtolnZO + (value of ~ftiln YeslerdayO 

turnoff "willy Ftolnfalr 



| turn on 

$ ] | Guest Motion 

Ai 


[ Import j [ Save As ] 

l Test J l Cancel 

[ save 11,—. 

* T 




XTetision rising 'Vanahh>s 


Speech Recognition 

Speech recognition with XTension Is inosi easily done via 
AppleScript lliat would look something like this: 

tel 1 app “XTension 4 * 
toggle '"Office Lights'* 

end Loll 
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Save as a compiled applet, in the Speakable Items folder. Name 
it "lights Please 1 "* 

XTension: Conclusions 

So, do l like XTension? Yes, However, I will warn you of a few 
things. 1 find the program a bit non-intuitive. 1 did si niggle at first 
with some tilings, but once 1 got diem, it was fine* The user 
interface, as we discussed, could definitely be letter. And, you either 
need a lloppy disk or image to deal with the copy protection,,, 
something that would lie better served by a simple .serial number, 

If you are going to do very simple filings, then you definitely 
want to go with blinking l lorne with die I x^tter user interface. If you 
are willing to go through .some teething pains, XTension is a great 
choice with great support* 

And, because of AppleScript, anything tbit you can do with 
your Mac, can he done by XTension. For example, XTension can 
send you email, or go to a web page, or whatever you want,., as 
long as you can do it in AppleScript. 

XTension sells for $99 through Sand Hill Engineering, Ibere is 
a widely used discussion list, with a Sherlock plug-in for the 
archives. Lastly, the web site lias some links to interesting places and 
examples on the web. <http://www.shed.com/> 


Editing events are easy in Thinking Home. The “Security 
Time Fluctuation" allows you to add a random number of 
minutes to the event. 



Thinking Home fritting an Bumt 

Macros are simply a series of steps. The Macro editor lets 
you see an overview of these steps m addition to editing 
each one of them. 


Thinking Home 1,1 

Now that you've seen XTension, Thinking Home will seem 
incredibly easy. Frankly, Bruce biwton and Russell Kusby-Smith, 
have done a really great job with the user interface. This 
program is an easy way to get started with PowerLine networks, 
l^fs lake a quick look. 

When you launch the application, you'll see a device list. This 
is well laid out with icons, and other pertinent information. Devices 
atv related to scripts and in short, it’s easy to grasp a lot of 
information very quickly from this window. 

Event and Macro lists are similar, you just press the tabs at rhe 
top of the window. And. similar to the “control panel 1 ' in XTension, 
there’s a "Remote ContioT in Tliinking Home that allows you to 
quickly control items in window. 
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trigger 






Device: 

[ Stairwell Motion 

*1 




Action: 

Turn On 

U 



| Cancel | f[ OK || 

Ihinking Home Flitting a Macro 

One thing that's different between Thinking Home and 
XTension is that XTension does not download macros to the 
interface,,, ever. Thinking Home can do this. So, if you want 
to turn your computer off or use it for other tilings, Thinking 
Home will allow you to download commands to the 
interface’s memory (if it has it). One thing to note, though* is 
that you lose the “if/rhen' and other forms of logic when you 
don’t have the computer monitoring behind the interace. 

Beware, though, interfaces can be a weak Link in your 
network. So t depending on the interface you are using, you 
may want to keep the control on your computer to avoid the 
Poltergeist effect. On the other hand, depending on your 
application, this can be an incredibly useful feature. 
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• Resource 
Installation 

Quickly Create Demoware - Easily turn your application into a polished 
demo. Just set the number of days for the demo to be active, paste in the 
graphics, and you’re done! 

Archive Freshening - Automatically update your installer project file; 
eliminate repeated searches for modified files. 

t 
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• Built-In 
Resource 
^ Compression 


Support 


Hierarchica 


Package 


Support 


Updaters 













'thinking Home Interface Tools 

Thinking Home tines allow you to run AppleScripts easily. 
Unlike XTension, you tin need to use a separate editor for the 
scripts. With Application switching on die Mac, this is not a big deal, 
provided you imvc enough CPU horsepower and RAM. 



‘Thinking Homo A/)j>leScrjf>t Interface 

One of the liest features of Thinking Home is tlie support of 
voice recognition and announcement speech. Basically, to get 
Ihinking ftonic to respond to speech, you simply Him on the cheek 
box "Respond to voice commands™ 

Now, think alx)ut this. You're now approaching Star Trek 
category, Take a installation that is using a wireless microphone. 
Now, you pull into the garage and want the lights inside to lie on 
for you. You simply say “lights on”, and Ixtause the Ixise for the 
wireless microphone is hooked into your Mac with speech 
recognition, lhinking 11 01 tie can <>1 >1 jge! 

in our example, we were pointed to Lotus Piuducttons in 
Seatde, www.kxaspnxlutlion.s,amr, (206) 5794320. Ihey cany a 
series of wireless niicmpl tones, and the model that lias a history 
working well Ls the Pro. 2 Wireless Microphone. Model WM-581/582. 



Winking Home Speech/Voice Cctfjabiliiies 

Thinking Home requires System 7 or later to run, and needs a 
Power Macintosh, iMac, G3 or Macintosh with a 68040 with 2 MB of 
RAM, and 3 MB of disk space. As you would expect, 
announcements require the Speech Manager (comes with the Mac 
OS) and voice commands require Plairifalk Speech Recognition 
(which Ls included on the 71 linking Honk* CD and on die web). 

Ihinking Home sup|Xiits direct CGI AppIeEvenls, *WWWff. 
This means that because you don't have to go through AppleScript, 
the response lime Ls very fast . The web integration that you can do 
Ls only limited by your imagination. For example, you could have a 
motion detector alert you via an AOL Instant Message, or a Pager, Lo 
mm to a web page with a web cam on it. 

ENTERTAINMliN T Nft-TWOKK 

Now, if you are like me, you also really want to blur die lines 
I let ween your computer system and your other electronics. The last 
year has made diis very possible... and here are a few examples. 

Tlie ZcphIR 

Just as tins article was gelling completed, a new player emerged 
in HA for die Macintosh, the ZcphIR! by StudioZee is an ADB device 
1 hat allows you lo control infrared. In other words, it allows your 
Mac to control CD players, VCRs. DVDs, receivers, satellite systems. 
Replay IV, televisions, and mote, 

One of the strongest features of ZcphIR! is its ability to help you 
manage and select your music CDs. With tlie freeware application 
NetCl), written by Toby Kush <http;//www.tobyrtish.com> > you can 
catalog your CD collection using an Internet database 
<http://vvwwcddb.com>. Once your music catalog is built, the ZephIR 
application allows you to drag the disc into ‘“magazines” teaching 
your Mac where each of your CDs are Icx iilexl in your multi-disc 
player You then ate free to create play lists of all varieties... not just 
by album title, but by artist or even the type of music. 

Imagine combining these capabilities with speech 
recognition. HA software, and a wireless microphone. Abu may 
lie in your living room and say “Computer: Please play Classic 
Rock.' The HA script could know to turn tin your amplifier via 
a Powerline device, send an infrared signal to the receiver to 
select volume and the source for the music, and then execute 
your "Classic Rock" play list. This is doable.,, today. 
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Programming Doesn't Have 
To Be This Difficult. It's REALbasic! 


up**!; 


^ * 1 ^^^ REALbasic is the award-winning, visual, 

object-oriented BASIC development 
environment for the Macintosh. 

Use REALbasic's visual interface builder 
and platform-independent language to build 
native, compiled—not interpreted'—profes¬ 
sional quality applications in a fraction of die 
time tL would lake in C/C++, Because our lan¬ 
guage is platform-independent you only need to write a single 
scl of code to create applications for both Macintosh and 
Windows. Leverage your C/C++ experience to extend 
REALbasie's capabilities using shared libraries, Mac OS 
Toolbox and W in 32 API calls or by writing cross-platform 
REALbasic plug-ins. 

Create prototypes, Internet applications, front-ends to 


databases, even games with REALbasic! Its OOP language 
employs everything you'd expect from a modem development 
environment—methods, properties, classes, subclassing, 
inheritance, constructors and destructors, virtual methods, 
and more. The IDE supports multi-threading, extensibility, 
TCP/IP controls, plus multimedia and QuickTime tools, 
and support for standards such as SQL, ODBC, AppleScript, 
and XCMDs. You can even import Visual Basic forms 
and modules. 

Go to www.realbasic.com NOW to download a 
FREE trial version or cail 512.263.1233. 

0 REALbasic 

REALbasic is a registered trademark of REAL Software, Inc 



***** 


H 

mi 



Best Nt-w Prtxiufl 



‘Free update for all owners of 
REALbasic 2 a and ai*}ve. 

Afl othor trademarks property of 
thnir mspective owners. 


Come see us at MacWorld New York — Booth #1970 










Now, obviously, you need to have die stereo traverse your 
house. There are wireless methods, but for my earn, conventional 
wired solutions are the only way to go. We used a series of Niles 
Audio products <http://www.mlesaudio.com/>. Through fairly 
conventional met Ik xIs, we set up 4 sets of remote speakers through 
their SPS-4 speaker selector, added volume c ontrols to each room 
(eg., a knob on the wall), and lastly; a series of weather resistant 
(for outside) and imwaH/in-eeiling speakers. 

Tl jcre is information available at a detailed level for Kxlay's 
electronics’ IR interfaces. For example, one of my favorite 1 rands of 
home entertainment is a brand called NAD 
<http;//NADdecm)nicsa:om>. NAD LINK (their name lor the IK 
command interface) is Ixisecl like mast home electronics IR on a 
standard created hv NEC yeans ago, (FYL There's a new standard 
called RC5, which is now' starting to take hold as well,) So, for 
example, here's a small snippet of NAD codes to control a variety of 
items on my main receiver (a NAD T77Q): 


Hex Code 

Description 

22 

MULTI ’SOURCE' VOL HP' 

23 

MULTI SOURCE VOL TOWN' 

25 POWER ON* 

2E 

5.1 E)CT INPUT 

2F 

LATE Nmr 

D3 

•TUNE DOWN* 

D4 

TUNE IF' 

D5 

•CENTRE VOL TOWN* 

D6 

'SURE, REAR VOL UP’ 

D7 

■SURR REAR VOL DOWN’ 

D8 

SUBWOOFER VOL UP’ 

D9 

SUBWOOFER VOL DOW 

You gel the idea. Now you can see how the capabilities of the 
ZephIK! are just limited to your imagination. 

We didn't have time to get a hill review of ZephIK! in place. 


but it's such a monumental prtxfuct for HA on the Mac, we 
wanted to mention it here. Those that have used it rave alxwt it... 
anti they're just getting started. And, because of the strong support 
already of AppleScript and XTension, you can do just about 
anything infrared with it. 

You can find out more about The ZepliIH! by StudioZee at 
<http://www.thezephir.com/>. 

Replay! Y: The Personal Television Server 

One of my absolute favorite, run away useful geek toys is 
RepluyTV, If you are like me, you've always been frustrated with 
cable IV or even VCR interfaces..* and dreamed of the day that you 
could just put a computer interface in front of recording, and record 
to a hard disk instead of tape. No tape changing, no continuous 
hassle of programming, just convenience. It's now here. 

I here are a couple of products out there dial allow you to 
record to hard disk in a consumer product. The one that we looked 
at was ReplayTV... and frankly, as corny as it sounds, it has 
completely changed the way I watch TV. It’s a tough thing to explain 
without experiencing it first hand, but HI give it a shot, 

basically, in tech terms, ReplayTV is a CPU most adept at MPEG 
11 recording and playback, It Iras significant disk space... mine has 


two 13 Gigabyte drives. It's got an infrared blaster, and a whole slew 
of input and output jacks for audio/video and cable There’s a built- 
in modem as well. It even hits a FireWire port for future expansion 
(although it's not supported as of yet). Replay IV is both a product, 
and a sen ice... not to forget an operating system* 

That's nice, But, what does it do? 

When you sei up die unit, it dials into the Replay IV network 
and downloads about a week's worth of programming for your area. 
The fust place you probably want to go is to see the "Channel 
Guide". Here, you can view an online 'IV guide — which Is updated 
each night via die modem to a kxnl number. Of you live in a remote 
area, you may want to verify dial die call is local) 

When you want to record something, say “Ally McBeaT, you 
hit die record buiLon... once for one time recording, and twice for 
guaranteed recording each week. So far. dial sounds not far off from 
a VCR... except you are now done.,, forever, For example, you 
don't Iiave Lo swap tapes in and out each week. And. you don't have 
to reset or recheck die VCR each week, Die latest Ally McBeal will 
always be there to watch! 



> Ally McBeal 




KIVU Cable 2 

9:00pm - 10:00; Starts In 12 minutes 6:48pm 

Clips and Interview* with cast members WghHflhl the show's 
most memorabks moments; host Bill Maher, Callsta Hoe* hart. 

Git Bellows, Greg Gorman, Courtney Thorne-Smith, Tracey 


CMDog 


Replay H ’ Channel Guide 


In addition to what you can program, ReplayTV has "zones" set 
up for you. This allows you to browse through what is playing even 
if you don't know what's on. 



Replay !V Replay Zones 


lastly, ReplayTV will allow you to set up “themes”. So, for 
example, let's say I want lo .see all Star Trek Voyager episodes, or 
anydiing to do with Tennis. I can set up separate rhemes, say one 
with the keywords ’Star Trek Voyagef and another widi the word 
“Tennis”, Replay!V will search the database its downloaded from 
die ReplayTV Network, and create these theme channels for you. 
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recorder, so you can actually pause 


!O00 flepfayfvjnt. 


Available at Best Buy, Circuit City and Amazonxom 


;*<£is You won't believe what you can do with ReplayTV It's not a VCR, it's a digital television 

iPSBE. 

Jive television, and do your own live instant replays 
It also has a search engine, so you can punch in a keyword, say "Golf," and it will find and record 
any golf program that comes on — all without videotape, Or you can just punch In the name 
of your favorite show and let RepfayTV find it and store every episode, so you'll never miss it 
again, if you had ReplayTV, what would you do? Call us at 877-rep3aytv or visit wwwreplaytvxom 


some televisions have all the fun 


O replay 





































Iteifword: "Tenrtfi 1 ' 
Start h completed. 

CtfchAtr s^jort,.. 

Sun 1/16 

*21 MSG 

Change 
search option* 

Ttnnti 

Sun 1/Jfi 

721 ESPN 

T«nrthi 

Mon 1/17 

4 fcftON 

Create the 

Arthur Aahi 

Mon 1/1? 

2*5 ARTS 

Them* ch*n/w*] 

Wlmfetedon-; Gr,,. 

Hon 1/17 

36® HIST 


Tends tBghUQh.. 

Turn */]i 

205 tHNSI 

Exit 

Tennis 

Wed I/l* 

20* ESPN 


Repiay7V SecirchingfJherne Channels 


ReplayTV can handle virtually any type of source: antennae, 
satellite, digital cable, analog cable, direct video sources, etc... 
The Re pi ay TV Service is a free service... there's no monthly fees. 
And, in case you are wondering about quality, it has three levels 
of recording quality.,, the lowest of which is more than 
adequate for watching weekly television shows. New versions of 
the OS are automatically downloaded and installed for you. You 
can use the skip feature to skip commercials, and the instant 
replay feature to see the last bit of what you just saw. And, you 
can watch something while it Is recording... even if it's the show 
you are currently recording! 

So, why has this "changed the way 1 watch television? 
Basically, 1 never watch television any more on the TV’s schedule*.. 

I watch it on my schedule. When 1 want to watch something, 1 
simply pull up the Replay Guide to see what 1 have recorded... and 
I select something to watch. Tliink about that. If you have kids, you 
never get them in Ixxl in time to .see the beginning of your show... 
it's always 10 minutes alter the show started. With ReplayTV, you 
can watch it it) minutes after it started... no problem. 

II this pan of the article sounds like a commercial, it’s Ixxausc 
I really like this product The only down falls lliat IVe experienced 
arc two fold. First, I didn't like having this unit in my bedroom 
because the hard drive made noise, 'ITiat was solvable (see the 
Channel Plus section below). Second, the iniiuil version of their OS 
was limited... and most of the items on my wish list were 
implemented in version 2,0. 

Replay*! V 3030,30 hours of Recording Time, $599.99- ReplayTV 
3020, 20 hours, $399.99. Replay Networks at 

<http://www.replaytv,coin> or 877-ReplayTV 

ChannelPlus: Whole House Distribution 

When we started the research for this article; we were 
presented with several issues and possibilities. One of the big 
ones for me was how to integrate the computer integration 
with entertainment setups. This not only includes audio and 
video distribution, but what about an infrared network that 
will actually work?! 

Tile problem you have is Quit you lutve all these devices that 
output audiu/video signals, but you can’t figure out how to have 
them play on all Qie I Vs in your house. Furthermore, for not only 
the A/V equipment, but also true proliferation of the control that 
ZephIR! can give you, you need to an infrared network. 

Enter GiannelPlus systems. 

Basically, here’s how it works. You have your central A/V area 
— probably in your family mom. Tliis is where your “stuck” Ls — 
VCRs, DVDs, ReplayTV, etc.,. What you want to do Ls take the 
output of some or all of these devices, and have them each appear 


on their own channel on all the TVs in your house. In my house, 
channels 80-89 are unused. Skipping one c hannel between to keep 
interference aL bay, we used channels 80-86, So, 1 have the ReplayTV 
on channel 80, Qie DVD on 82, UserDisc on 84, and my Home 
Automation server on 86. 'Ihe home automation server not only 
outputs to a computer moniior. but also uses Qie video output we 
have built-in to a Performs, Tliis output goes into the ChannelPlus 
unit — and that way, I can sex* the status of whar’s on, and whit's 
not, everywhere in the house on channel 86! 

Other possible solutions aa j to have one or more web cams go 
not only to the web, but to the TV coax network in your house. 



ChannelPlus: Distribution Fund 

ChannelPlus has a variety of different solutions. They have 
trackage solutions (all-in-one, or all-in-two), and they individualized 
modules. In addition, there are standard modulators, as well as ones 
that am handle stereo and surround sound. 



ChamidPius: j4W Scat’s Modafators 


It you are kx)king to just get the kisic functionality of moving 
A/V onto Qicir own channels, then take a serious look at the 3400 
series. In tliis type of network, you gel two 44 boxes". One Qial goes 
at your stac k — where you plug in all the A/V into the modulator 
The second goes at your point of distiibution (usually in the garage 
or an attic). Hus allows the coaxial output of the modulator to lx* 
“merged" back into the coax distribution of the house. 



Channel Plus: Infrared Target (#2133) 
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In this 3445 setup, we simply plugged in ;i “infrared tmgef (the 
2133) at cad i location Uial wc wanted to control 1R. Tills is a small 
box dial sits on axtx in lx.-tween the wall jack and your TV. This box 
lakes your IK signal (when you point your remote or ZephIK at it), 
and converts ii into a 5 volt signal and puls it onto your am 
“network”. In my experience, this methodology works far belter 
than many of the IK -> RF converters that are on the market. 

If you are neatly gung ho on this stuff, and budget is not an 
issue, you should look at ChannelPlus' l^est qu;iHty stuff. Realize that 
putting these types of modularized systems does take planning and 
understanding,,. and it may be easier to just leave it to a professional 
installer. Be forewarned, the more modularized systems are complex 
enough that you are likely to run into minor gotchas here and there. 
There's nothing wrong with these solutions, but given how many 
more pieces there art: (due lo more and higher quality modules), 
they are simply more complex, 

One of the benefits to these higher end systems is that the 
infrared network is two-way which could be of use to certain 
types of needs. They also have the obvious Lid vantages to Stereo and 
Surround Sound 

If'you haven't figured it out already, ChannelPlus really shines 
in conjunction witli not only ZcpIiIR!, but also ReplayTV. In fact, it 
turns ReplayTV into a real 'Television server because it gives your 
house a video network* 

Now, in doing this, there are a whole series of issues dial you 
should realize up front. First and foremost is that you are going to 
need to have Lin additional nm of coax from area near your ‘"stack” 
to the distribution point. This is for the output of the modulator* 

You should a 1st.) realize that these are all modulators. By 
definition, they will never output the quality of a DVD — they will 
typically be around the quality of a broadcast signal over analog 
cable or antennae. Titty will be much letter quality titan the 
Channel 3/4 modulators built-in to your VCRs, 

The Channel PI us systems are really meant for installers to 
install for you. Bun being of the technical crowd, you can likely do 
it yourself without much difficulty. Be forewarned, the manuals 
have lots of little tidbits in them scattered all over the page — so 
read the manuals thoroughly Indore pnseeding and you will save 
yourself a lot of trouble, 

lastly, you are dealing with an analog signal here. So, any 
thoughts that you might have on splitting signals, etc*.* are going to 
cause you trouble. Yes, you can usually split a stereo signal and get 
away with it. But* video signal is not so forgiving and if it survives 
one split ok. it definitely won t survive two splits, 

Now. there are some folks that wonder what products like the 
ChannelPlus line of modulators have to do with a magazine like 
MacTech. fm sure that you now see that Home Automation is 
ultimately not about computers, but controlling your environment. 
And, ChannelPlus gives you a way of interfacing your 1R computer 
control with devices in your home. Furthermore* it allows for you 
to have a television network to Lake advantage of oilier 
technology. For us, the ChannelPlus network is what ties much of 
our household network together 


Moving Forward with Home Automation 

There are so many things that we didn't cover here, For 
example, what about HVAC control and duct dampens? Or the brig 
list of automated items: Pet feeders, aquarium equipment, garage 
dcx)r openers, deadbolts, blinds and drapes, alarm/sccurity, 
driveway sensors, gate openers, etc. 

Here at Mac l ech, we always want to know what you think 
about articles. But, this article* more than most, really has us curious. 
We really want to know what you think about this article. Did you 
find this article interesting? Do you want to see more articles alxn.it 
writing scripts for Thinking Home and XTension? Do you want to 
see coverage of Other technical home products? Let us know at 
letters@mactech.com, edltorial@mactech.com* or if you want to send 
.something to me personally, pub1lsher@maaech*C0m. 

If you are going to be serious about 1 lame Automation, realize 
that you need to te prepared to invest die time to make it work. 1 
can tell you that this article was supposed to lx-* written six months 
a#o : I nit every lime we kx)kcd around, die project grew and more 
things were added. Most people will tell you of similar situations. 

It can be enormously fun* but it can also be frustrating. 
Get yourself equipped with the right tools — and get help 
installing the electrical hardware if you aren't used to doing 
basic electric installations, And. set things up using bridges, 
fillers, and other methodologies to prevent problems from 
entering into your network. 

You should seriously consider joining the mailing lists like 
XTension list* or the a>mp,home*automation newsgroup. 

And, as lor all of the products that arc 1 more technical in nature, 
RTFM... or put more politely, do yourself a favor and read the 
manuals cover to cover before installation. 

But most of all.., enjoy your home of tomorrow. 

Special Thanks 

This article was so broad, it drew on a number of sources, 
.Special thanks to the following folks for helping out in the 
research of this article, or with descriptions: Bob Sherman and 

Pam Winikoff of Levi ton, Pete Schwartz of ChannelPlus, Bruce 
Lawton of Always Thinking, Michael from Sand 1 lill Engineering, 
and last but not least. Jay Pryor Lind Jeff Brandt who helped 
with the hard wire installations. 

Where to Buy? 

'there are a large number of places on the web that are sources 
for X- 10/PowerLine products Here are jusi a few,.. 

* Advanced Sendees Inc. <http://wvvw.asihome.coni> 

* The Beehive <http://www.bzzzzzz.com> 

* ChannelPlus Reps <http://www.channelplus.com/saloshtfn> 

* \ lame Controls, Inc, <http://homecontrols.com/> 

* I lame Tt>vs <http://www.hometoys.com> 

* PCI Automation <http://www.rdautomation.com> 

* Smart Home <http://wwwsmaTthomexom/> 

* Smart Home USA <http:/AAWW,smarthomeusa,com/> 

* X-10 <http://www.x10.com/> 

* Tlie ZcphIR! <http://www.thezephir:com> im 
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TOOLS OF 
THE TRADE 


By William Allen 


Apple Help 


An Introduction to 
Apple’s HTML-based 
Online Help System 


Overview 

At some point in your project's 
development cycle you will come across 
the issue of how to provide assistance to 
your users. Whether your project is a 
stand alone application or an interface 
to your hardware product* an online 
help system adds a level of polish in the 
eye's of your users. Online help is 
defined as being able to access 
interactive and searchable help content 
from within your application via the 
Help menu which the Mac OS provides 
to all applications displaying a menu or 
via a Help (?) button. 

There are have always been various 
solutions to providing online assistance. 
You can roll-your own or outsource this 
task to a third party solution such as 
Altura's Quickilelp, or you can use the 
online help system that Apple includes 
as pari of its Mac OS operating system.. 

Apple's solution, called Apple 
Guide, was introduced with System 7, 
The good news about Apple Guide was 
that it finally formalized ihe process of 
creating online help for developers. The 
bad news was that the cost of admission 
in working with Apple Guide was quite 


high. Despite the fact that it looked very cool and had some 
great capabilities, creating an Apple Guide involved learning 
a set of proprietary script commands embodied in the Apple 
published 600 page book and CD combination* Apple Guide 
Complete: Designing and Developing Onscreen Assistance. 
With the rapidly changing pace of software development, 
Apple Guide was too cumbersome to learn and maintain. As 
a result, the payoff was rarely worth the effort and Apple 
Guide floundered, never seeming to reach its full potential 
So, since Mac OS H. 6 Apple has quietly been upgrading 
its Mac OS online help system. The Internet, of course, has 
changed everything. Fin guessing that Apple recognized that 
there had to be a better way for developers to create and 
integrate their online help solutions into their applications. 
Their answer lay in the integration of their crown jewel 
technologies and the presentation capabilities of HTML into a 
more accessable solution now called Apple Help, 

You should consider looking into Apple Help because it 
offers considerable benefits to you as a developer by being 
very simple to implement and manage, while tapping into 
some of Apple's strongest technologies. A more significant 
reason to took into Apple Help is because, according to 
Apple, this will be the operating system help engine used for 
Mac OS X and beyond. 


Under the Hood 

The heart of Apple Help is an application called the 
Help Viewer, which operates with support from the HTML 
Rendering Library extension (HTMLRendenngLib). 


William Allen is the Senior Graphic Designer for Transdigital Communications Corporation, an in-flight entertainment 
corporation in Brea, California, In this role he produces interface designs for interactive systems for the travel and leisure 
industry. He has been working on a Mac since 1984. FTe can lx* readied at wallen@m3c.com. 
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Figure L The Help Viewer application. 


The Help Viewer is a lightweight browser based upon the 
HTML 3.2 specification. It supports all HTML 52 features except 
forms and plug-ins, Java and a deliberate restriction of only 
being able to handle one frame set on a page. To offset these 
limitations the Help Viewer taps into some very cool Apple 
technologies to integrate itself with both your application and 
the operating system to offer a high degree of interactivity. 
These Led 1 no logics are: 

• Sherlock-Apple Help uses the Sherlock search engine to 
allow users to find specific information within your content. 
You facilitate this feature with an indexing process, pan of 
which is strategically embedding HTML <META> rags 
throughout your HTML pages. You then run your indexed 
pages through an indexing tool which reads these tags and 
generates an index file of your content. These HTML tags 
allows you to control the indexing process. 

• AppleScript-Apple Help becomes interactive with the 
ability to execute AppleScript scripts. To execute AppleScript 
scripts you embed <A HREF> hypertext links in your content 
which point to your scripts for execution, 

• QuickTimc-To Play QuickTime movies you embed 
<EMBED> tags in the body of your content along with some 
parameters to indicate how the movie Is to be played 

HTML serves as the framework to these technologies so let's 
look at part of Apple Help first. 

Getting Started 

Tire process of developing a basic HTML Apple Help 
involves four steps: 

• Organizing and creating your content with HTML. 

■ Making your content searchable En an intelligent manner with 
four <MFIA> lags sets. 

• Creating a title page for your book so that your book is listed 
in the Help CenLer. 


Winner; Best Apple Technolog)' Adoption n Apple Design Awards 2000 


Home 


■ : : : i X-10 home automation software for MacOS 


Thinking Homed is the ideal blend of power and ease-of-use. 
No other Macintosh home automation software delivers so 
much for so little! 

\ Easy to use. Very well-designed, clear user interface. 

T Unlimited power. AppleScript and voice commands provide 
users maximum customization options. 

T lowest price. At $39, Thinking Home is an exceptional 
value, offering users superior features such as: 

4 Drag & Drop 4 Stores events and macros 

g Speech Recognition 4 AppleScript and direct CGI support 

4 Desktop Devices 4 Support for Firecracker, ActiveHome 

4 Thoroughly integrated AppleGuide and CP-290 
4 Imports MouseHouse documents 


But.,.what do current Thinking Home users think? 


iOvery very impressed with the user interface. Very welt done, i 

- Tom Carstenson 

iGreat product, great price.! 

- Todd Pardun 

iThere are few software companies that are so responsive, i 

- Larry Lloyd 

il really like the Thinking Home interface 6 His clean and well thought out.} 

■ Richard G. Darenberg 


Thinking Homeis interface surpasses other X-10 products! 
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Download Thinking Home now at www.aiwaysihinking.com/thintro.html. 


For only $39, MacOS users can capture the power of the X-10 

standard! . 

Order online: 

www.alwaysthinking.com/thintro.htnil 
Phone Orders: 

(800) 556-9559 (US residents only) or (843) 986*0308 


Want more X-10 gadgets with your Thinking Home 
CD-ROM? Visit www smarthome com 


Always Thinning, Inc. QJ? 
Beaufort. SC 'f‘ 
(043) 3SS-0308 r\ 
























































• Creating a Help menu item in your application so users cm 
jump to your help book from within your application. 

Organizing and Creating Your Content 

Developing a blueprint based upon the goals of your 
presentation Is essential to a successful Apple Help project. 
A good way to start is to divide your content into static and 
dynamic capabilities. A static presentation would be those 
elements that are informative such a table of keyboard 
shortcuts and Hie like. Dynamic elements could coach or 
assist your user through a process or steps such as launching 
a browser to your web site or some other action like playing 
a Quick l ime movie to explain a concept. 

To create yotir content in HTML, you have a wide variety 
of choices at your disposal. You can use any authoring tool 
which outputs standard HTML 3-2. Your file names can end 
with either the Mum" or Mu ml" extension. You can link to 
other pages, create tables, and display graphics as you would 
in building a conventional web site. You can view and check 
links of your work in progress with any standard browser 
like Netscape's Communicator or Microsoft’s Explorer but 
you should view your work in the Help Viewer to check the 
dynamic functions because off-the-shelf browsers interpret 
the various tags. I’ll introduce to you about shortly, 
differently than does the Help Viewer. This point will 
become apparent as we move along. 

Understanding how Apple Help is structured in the 
operating system will help you organize and manage your 
material. If you visualize Apple Help as being a local web 
sire then the organization and management of your content 
will be a breeze. The folder or directory structure of Apple 
Help is (|uiLc specific up to a point but offers lots of latitude 
once you gel past that point. Let's take a peek. 

Look inside your System Folder for the Help folder. 
Inside the Help folder you II see some folders with one 
solitary file named Help Center The Apple Help Viewer 
folder is where ihc Apple Help Viewer application and its 
support files exists. This arrangement of having the Help 
folder inside the System Folder provides a central and stable 
location lor the HTML material you create. Go ahead and 
double-click the Apple Center file and you should get access 
to the Help Center just as if you selected the Help Center 
menu item from the Kinder's Help menu. If you make a side- 
by-side comparison to what s listed in the Help Center topics 
window with the folder names in the Help folder window 
then you'll see the connection between the folder names and 
the Help Center listing as shown in Figure 2, 



Figure 2 Help Center and the l lelp folder compared. 


Since we 1 re already kx)king in the Help folder, try this: Quit the 
Help Center page by closing the window which quits llie Help 
Viewer application. From the Finder remove the Help Center file 
outside the I lelp folder to, say, the Desktop, Launch the Help Center 
menu item from the Finders Help menu and then look In your Help 
folder again. Whoa ? its a brand new Help Center file! 

Based on this exercise, we can figure out that one of the Apple 
Help Viewer's functions is to automatically create a table of contents 
of the various help folders existing in the Help folder To make this 
dynamic listing work you have to register your help content with the 
Help Viewer, Liter, 111 explain how you get the Help Viewer to list 
anti link to your help content in the Help Center page. 

Before we go further in our explorations, lets imagine a classic 
organizational analogy of I rooks, chapters and pages to help us 
understand what were kx>king at. All the folders iaside the Help 
folder will l>e lxx)ks. All the folders inside the lxx)ks will be 
chapters. Finally, all the files inside our chapters will be 
pagesMTTML pages to Ix j exact 

An 1JTML page, is typically made up of some combination of 
words, pictures, and hyperlinks. Taking a due from standard well 
publishing conventions, inside each chapter folder you'd !>e wise to 
create one folder lo put all your IITML pages into and another folder 
to house your graphics and other media. Maintaining your help 
hook w ill lx determined by how organized your assets are, So now 
its up to you and/or your team to outline your content in this natural 
!xx)k, chapter, page analogy to suit your goals and go to work. 

I'm placing a lot of emphasis on planning your content ahead 
of rime because the process will help you identify what capabilities 
you wish Lo integrate into your particular help btx>k as well as the 
steps to achieve your goal of assisting your users. 

Apple Help 12 SDK 1.0 

Apple provides a software development kit (SDK) which will 
get you running in no time. You can download the SDK from 

<ftp://ftp.apple.conn/deve1oper/Development_Kits/Apple_Help_1.2_$DK_1.0.sithqxx 

The SDK coma ins all the lexis for making your job a lot easier. 
HI point out the tools you’ll need as I go along but feel free to 
explore the test of the SDK on your own. 

'The firsr task is to convert your content into HTML as 
mentioned earlier, if the prospects of starting from ground zero seem 
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daunting, fear not because Apple provides some pie-made 
templates with generic coniem for you to use as a starting point. 
Look inside the SDKs Complete Books folder within the Samples 
folder. There’s a simple help book as well as a more complex 
version for you to use. Make a copy of either one of these IBooks 
somewhere convenient and then launch your favorite HTML 
authoring tool and create your help book. There are tons of software 
and ulx)ui a l>izii!ioo books and web sites devoted to this topic so I 
won’t present any of that here. HTML 52 is the Ixieklxjne of your 
Help content but rememl^er the restrictions mentioned earlier. 

Sherlock 

When launching any page with the Help Viewer you’ll see a 
navtgaLk >n/seareh interlace at the top of die page's window, tliis 
interface consists of three navigation buttons and a search text 
fiekL button combination. Your user will always have access to dlls 
navigeUion/scardi interface no matter w here tliey go in Apple Help. 
Hie search interface is how the user accesses the Sherlock scareli 
engine by typing a query and hitting the searc h button. 

In order for the Sherlock search engine u> process a query 
and find any hits in your pages, you have to first index your 
content with the Apple Help Indexing Tool provided with die 
SDK in the Authoring folder. The result of this process is a 
separate index file reflecting the contents of your txx>k. When a 
user does a search, the search is performed on this index file 
rather than all the pages in your hook. This strategy accounts for 
the speed in which a search can occur. 

Before you use the t<x>l to index your book you incorporate 
any combination of four <META> tag sets into your pages to 
control what the Indexing Tool indexes. Without these tags, the 
Apple Help Indexing Tool will indiscriminately index your help 
book willy nilly. This is the point where all your earlier planning 
pays off Ixrcause your blueprint will guide you on what tags to 
use. Wliat follows explains what these tags are, what they do. 
and where to place them in your pages. 

Controlling the indexing 

Placing the ROBOTS meia lag in your file’s HTML header 
allows you to control law your content is indexed by die Apple 
Help Indexing Tool There are four different values or attributes to 
tills tag: INDEX, NOINDEX, SEGMENTS, and KEYWORDS. Ill 
explain each in otxler and why you may want to use the tag, 

<HETA NAME="ROBOTS* OQWJWfP®"INDEX"> 

* lliis tag/attribute com!unatk>n tells the indexing uxit to go ahead 
and index the entire page including all its segments and 
keywords which HI explain about in a moment. 

<KETA NAKE^ 4 'ROBOTS’* OmWL^W INDEX*) 

* This value has the opposite effect by telling the tcxil to not 
index this page at all. There's no point in indexing a table of 
contents page, for instance, so this type of page is a good 
candidate for this tag/attribute combination. 

<MKTA NAME-"ROBOTS" CONTENT-"SEGMENTS") 
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» This tag/attribute combination tells the indexing tool to only 
index segments within you file which can also contain the 
next attribute KEYWORDS. 

<KETA NAME-"ROBOTS" CONTENT-"KEYWORDS M > 

• This tag/altribuie combination causes only the words 
specified in die KEYWORDS tag to be indexed 

Segments 

'Ibis tag set is essentially a comment which allows you to divide 
your material into multiple sections within one HTML file. You place 
as many segments in the Ixxty of your content as you would a 
standard 1 1TML comment tag. Each segment will alum a separate 
"hit 1 ' from the search engine even though they originated from the 
same [xige, Segments work very well if you would tike to organize 
a topic into a family with various members into one file rather that 
breaking them up into separate HTML files. Note tliat each 
AppleSegStart comment must end in an AppleSegEnd comment. 

<i-AppIcScgStaxt ="5etting Preferences* > 

<A NAME="Setting Preference^X/A} 

O-AppieSegDescription “"This section describes how to s*r the 
Preferences for tny application**^ 

<<Content of Segment >> 

<!-AppleSegEnd > 

Adding keywords 

It’s not always possible to anticipate how your user will 
search for help. Adding additional search synonyms, called 
keywords, enhance your indexing strategy by allowing your 
users to zero in on the concept they’re kxiking for in a way that 
works for them. For instance, if you have a page devoted to 
explaining the options in your application's preferences you may 
want to include the KEYWORDS tag in your header as follows: 

<META NAKE="KEYWORDS" CONTENT-*preferences. setting 
preferences. How do I set preferences?. prefs* options, 
selections"} 

This lag works very well especially if you do not have 
those particular words or phrases in the content of your 
page. Each of the words or phrases listed will return the 
same page as a valid “hit, 1 * 

If you would like u> add keywords to a segment then you 
use Lhe following comment tag within the relevant AppleSegStart 
and AppleSegEnd tags explained earlier. 

£HAppleKcyvorda ^"preferences* setting preferences* pieis, 
options, selections”-} 


Adding descriptions 

Finally, there is a DESCRIPTION lag which will return a 
brief description in the search results with each hit. 

<M£TA NAME-”l)RSCRimorr CONTENT-"This seer I on describes how to 
change the Preferences"} 

These four simple tag/attribute combinations provide all the 
necessary capabilities you need to control the indexing process. 


Using the Indexing Tool 

Having gone through the alxjvc steps, your help book Ls just 
alxHit ready for indexing. It should liave the final directory structure 
with die above HTML indexing tags in place. The last step Ls to 
merely drag and drop your lxx>k on Lop of the Apple Help Indexing 
Ttx)l located in the Authoring Tools folder of the SDK. Thai’s it! The 
result is an index fife which you include with your help lx x)fc* 
Remember, if there Ls no accompanying index File of your help 
book, then your users cannot search your book. 

You are free to create as many index files that makes sense for 
your txx)k. For instance, if your Ixsok is simple then one master 
index file might be all that you need. However, you could also 
create a series of smaller index files for each chapter. Tf your 
application were progressively mcxtular in nature, for instance* then 
you could have a separate help chapter with its own index file with 
each module. Maintenance becomes localized rather global. Each 
strategy has its valid depending on your own situation. 

If rhe tool reports an error or warning it probably has to do with 
your directory structure or tag formation, Select the enor/waming to 
see the cause of the problem in your file. 

Creating a Title Page 

Now we need to register your newly minted bcx>k with 
Apple Help so it will both appear in the Help Center and link to 
your look's title page. You use the AppleTitle rneta tag in the 
HTML header of your title page to accomplish this task, 

<META NAME-"AppleTitle" CONTENT="My New Help Hook"} 

The HTML title page should ho at the nxX level of your Ixxik. 
Einally, place lhe whole help 1x»ok folder in the Help folder in the 
System Folder along with all Lhe other help books which may exist 
there. Delete the 1 lelp Center file as we did earlier, Now launch the 
I lelp Center menu item in the Finder's Help menu. The Help Viewer 
will generate a new Help Center file as we T ve seen earlier You 
should now see your new help Ixxik listed in the Help Center. 
Congratulations! Walk through your help lxx>k by clicking on links 
and do some searches to see how ii all works, 

Of course, the first pass through will reveal any broken 
links, etc. in your lxx»k. Just go back into your HTML authoring 
environment and fix those until you've squashed them all If the 
searching does not work as you'd like then merely add* delete, 
or modify the appropriate tags and regenerate a new index file 
or files until ii works as you’d like. The development cycle is 
minimal if you stay oiganized. 

There are some other visual attributes you can influence with 
minimal effort such as the icon displayed for the link to your hook 
in the Help Center. If you do not provide an icon then rhe 
application provides a generic one. I hope you II want to mil up 
your sleeves and check out the SDK s reference section to add some 
Final |x>lish to your help hook. 

The Final visual |x>lish is to liave your HTML help files display 
the "Question Mark" icon in the Finder associated with the Help 
Viewer. Your book will work just fine without this icon but to add 
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it is trivial. To give you this Kinder icon, change the file's have a 
creator axle to "hbwr" and creator tyj>e of “TEXT". Some HTML 
authoring tools such as BBEdit allow you to save your work with a 
different creator code other than its native one. The advantage to this 
is you progressively create files with the icon you want as you work. 
If your authoring too! does not have this feature then you could 
create an AppleScript applet to automate this resource uk xlihcation. 

Creatfnc Items in tiie Menu 

Now it’s Lime to move out attention to the final steps 
which is to link your application to your help book hy 
creating a Guide file component which points the Help 
Viewer to your particular Help book. 

Create a text file with Guide Script commands 

Make a copy of your final compiled application in the Finder 
Open up a text editor like .Simpletext and type in the following 
Guide Script commands, 

(Help ffenu> w HyApp Help" .help. "?’* 

<App Creator)'abed* 

(Startup Window) presentation* "Empty Sequence" 

(Version)"!.0 fHy Software Company* Inc* 2000"."1*0“ 

(Balloon Menu Text)"Displays information and ins tract ions for 
using HyApp," 

(Define Sequence)"Empty Sequence" 

(Define Pan el) "Empty Panel" 

Empty Text 
(End Panel) 

(End Sequence) 

Save this text file as “MyApp Guide Source" in Lite same folder 
as your application. The' first command's parameter Ls a list of the 
menu items listed in your applications Help menu. Hie second 
parameter Ls your application's four letter c reator code* The <Balloon 
Menu Text> command is the text displayed over this menu item 
when the user has Show Balloons menu Item turned on. 

Create a resource for the Guide file 

Launch ResFdit and create an new empty resource file named 
“MyApp Gukic.rsrc in the same folder as your application and text 
file “MyApp Guide Source" you just created 

Create a new resource item ‘htmT with an id 1000* This 
resource item tells the Apple Guide that this Guide file 
coma ins menu items which should he redirected to HTML 
help content* Save the file* 

Next, create a new resource item in the same resource file of 
type ‘TEXT and dick OK. 

Open the TEXT resource and type die relative path into the 
TEXT resource, which in this example is: 
MyApp%20Book/myTitfePage,htm. This Ls the URL which geLs 
passed to the Help Viewer when the user selects the "MyApp 
Help" menu item from Lhe Help menu* Note the hexadecimal 
notation for a space character (%20) in the URL path which is 
relative to the Help folder Close this window* Change the name 
of this TEXT resource item to something like “MyApp Help". 

Close all your windows, save the resource file and quit ResEdit* 
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Linking your application with your help book 

In tile SDK s Authoring Tools folder find the Guide Maker 2.0 
t(X)l. This tool compiles the text file and resource file we created into 
an Apple Guide file. Tilts file ties your application s 1 idp menu item 
and your help Ixxik all together. 

Launch the Guide Maker. From the Idle menu select 
Import Source and select the “MyApp Help Source' 1 text file 
you created earlier. Save the new Guide Maker file with the 
name “MyApp Guide.gm* in the same folder as your oilier 
resources and application. Select Compile from the File 
menu. Save this file as u MyApp Help* in your applications 
folder, When the file is compiled it looks lor a resource file 
with the same name as the guide file hut ending in “.rsrc‘\ If 
it is found, then its resources are copied into the new Guide 
file. Quit the Guide Maker application. 

If the Guide Maker complains or reports an error, go 
hack a review the previous steps carefully to make sure all 
your resources are correct and named properly. 

If all went well then you’ll see a Guide file in the same 
folder as your application. At this paint, you run launch your 
application and check out the Help menu items. You should see 
the “MyApp Help" as the first menu item in the Help menu. 
When you select this menu item, the Help Viewer will launch 
and you will lx* taken to your Help lxx»k. Congratulations! 

Once again, explore 1 the SDK for further variations like 
adding multiple menu items In she Help menu. For 
integrating a Help (?) button within your application, the 
SDK contains Power PI am files for you to use in your 
application's source code. 

Adding IrnioiAcnviiY 

I’ve outlined the basic architecture of planning, implementing 
and attaching a help tx>ok to your application. Once you’ve 
established this framework, adding interactive features using 
QuickTime and AppleScripts is achieved with two tags as follows: 

Quicklime 

Hie essential rag to placing a QuickTime movie into yovtr 
content is an <EMBED> tag. 

<EHBKD SRO" ayMov ip.no v"> 

The SRC lag is a relative path to the movie, Additionally you 
add WIDTH and HEIGHT attributes to Lcll the ! leip browser the size 
of your movie. The introduction of QuickTime 4.1 added 
AppleScript capabilities to the Quicklime Player application. This 
opens up some fascinating fxassibilfties which are outside the scope 
of this article but are certainly worth exploring. 

AppleScript 

One of the most exciting features of the Apple l lelp System is 
its ability to run AppleScript scripts. Your scripts ate triggered with 
hypertext links which you emlxxl in your page* as follows: 

<A HREF= * he 1 p: r miser iptHyAppXiOCuide&ook: MyAppXSr r 1 pt s: 

MyScript.src w ‘>Ciick me</A> 


The link begins with an opening Anchor Tag: <A 

this is followed by a hypertext reference tag 11KFF= with a 
command value: help:R»nseript= followed simply by a relative path 
to the script file with a dot three letter extension of ,src. The Anchor 
rag is completed with the dosing bracket; >, 'Ilien follows the text 
which is displayed to the user : Click me. Finally, the link is 
completed with the closing Anchor Tag: </A>. 

Since this link is a command to run a script, you can 
Optionally pass your AppleScript script data using the 
optional STRING parameter. You place this parameter after 
the script's path but before the single quote as follows: <A 
HREF= , help;runscript= ,f MyApp%20GuideBook:MyApp%Scripts;M 
yScript.sre" SIRING^"myData M1 >Click me</A>. One sc ript, then, 
can be multi-functional by merely passing a different 
parameter. If the script launched a browser, for instance, you 
could pass different UKLs as a parameter 

On tile other end. your AppleScript scripts use the 
following special handler to receive the information sent by 
the script link as follows: 

on t^vent heiphdhp* (rayData) 

-script goes here 
end cevent heiphHhp* 

Hie event handler used by the Help Viewer application is 
written in the raw axle formal which uses the chevron characters 
and alphanumeric code* This example shows (he optional passed 
variable myData within the parenthesis. 

besides these few requirements, implementtpg AppleScripts to 
control any aspect of the Mac OS or any other script able application, 
including you own. is up to you, 

CoNcuvaoN 

Tlx Supple I lelp SDK provides a wealth of samples and 
templates for you to begin adding a professional level of Help 
capabilities to your project. Overall, its strength lay in seamlessly 
blending die best of two worlds: ! fFML and the MacOS. Apple has 
certainly done a fine job of addressing the needs of developed and 
users alike with its new IITML based Help System. 
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PROGRAMMER'S 

CHALLENGE 


by Bob Boonslra, Westfoul MA 


Ri h*k Rotation 

Readers sometimes write me to ask whether they can 
solve the Challenge on a platform other than a Mac, Now, Vm 
not sure why a reader of rhis publication would want to do 
that, buL in many cases the Challenge is platform agnostic 
and quite amenable to solution an another machine. 
Sometimes I get mail thanking me for creating non-Mac - 
specific problems. Then again, 1 also get mail asking why 
problems that have nothing to do with the Mac appear in a 
Macintosh publication. Paraphrasing Lincoln, you can’t 
please all of the people all of the time. But it has been a 
while since we’ve had a Macintosh-specific problem, so 
we re going to offer one this month. 

The last Challenge 1 competed in required readers to 
solve the puzzle known as Rub*k*s Cube, a 3x3 cube of 
smaller cubies where each cube face was colored with a 
different color. Solving that Challenge look me right to the 
midnight deadline, past many midnights before that one. and 
actually pushed me over the edge into Challenge retirement 
(as a contestant, anyway). As I write this column, having 
watched another midnight come and go. 1 thought we’d 
revisit the Cube, but from a completely different perspective* 

Your Challenge this month is to write a program that will 
display the cube, animating both rotations of the cube and 
the moves used to solve the cube. The prototype for the code 
you should write is; 

typed enuu \ t identify the cube face 7 
kfrontKt. kBack. kLeft. kRight. kOp. known 
K CubeFsce: 

typedef enum I /* identify the axes <tf rotation 7 
kFrontEack^U, kLeftRight, kUptlowu 

t rotation axis kXY is oriented viewing face X, through the cube, toward face Y 7 

I CubeAxis; 

typedef enum I 

kClockwiEe=l, kCounterClockise^ 1 
] TurnDirection; 

void TnltCube{ 

CWtndowFtr cubetfindow. 

r window where the rotating cube ^liould lie rendered 7 

const RGBColor cubeColors[&j. 

r colors to use in rendering, indexed bv CuheEace 7 

const short cubieCo!ors[3][31[3], 

r cuhicCotofS is the index into cuhcColors for individual cubks 7 

F t iibef’olorsfcubjcColorsitl [r| [cl] is the color of the cubic on face f, row r, col c*/ 

r Row and column orientations arc as follows: 7 

r eubieColors|kFnmtHO][l)J is adjacent to klip and kLeft 7 

t cubieCoiorsikFront][0ji2] is adjacent to kFp and kRiglit 7 

r tubkt:uloniikBack|[0] |0| is adjacent to kCpand kRiglu 7 

r enbleCotorsfkBajck) 101121 b adjacent to kip and kUft 7 

reijbieCnbrsikLcftifOflO] is adjacent to kCpand kBack 7 

r aibkColorsfkLefti[0j[2] is adjacent to klip and kFront 7 

/* eubleColorsj kRightl [D] [0] b adjacent to klJpand kFront 7 

r aibieColorsikKightjifl] [2] is adjacent to kUp and kBack 7 


P cubieG>lors[klJp][0][01 is adjacent lo kBack and kUft 7 
/*cul>ie€<dnrslkllpl [01f21 Is adjacent to kBack and Right 7 
r vuhieCadnrsikDown||U||0 , | is adjacent to kFront and kLeft 7 
r cubieOilorsjkDown jjoj[2j is adjacent to kFront and kKiglit 7 

short cubeWidth, 

F in pixels of a cube in the standard orientation (kFront visible) 7 

short stepSize 

/* granularity to redraw, sTrpSize steps b one full 360 tlegree rotation 7 

); 

void QuartsrTum( 

Cube Face face * P turn this face one quarter mm 7 

TurnDlrectitm direction t turn the face in this direction 7 
P turn fmentation b looking at the face from outside the tube toward the center 
of the eulx: 7 

h 

void RotateCubef 

CubeAx is axis, t rotate cube about the specified axis 7 
TurnDIrection direction, 

t rotate the cube in this direction about the specified axis 7 
P clockwise about the kFromBack face is determined viewing from the kFront 
face, through the cube to the kBack faee 7 

short stepsToTurn 

b 

void TpntiCube(void): 

This Challenge will start with a call to your JnitCube 
routine providing a number of problem parameters. The 
window in which you should render ihe cube, a color 
window with a pixels tee of 32 bits, will be provided in 
cubeWindow. The colors making up the eube faces will be 
provided in cubeColors. and the individual cubic colors will 
be specified by cubieColors as indices into cubeColors. You 
should center your display of the t ube in the CubeWindow, 
and size the cube so that it is cubeWidth pixels on a side, in 
its initial position, oriented along the u.-v axes, and viewed 
along the eube normal, InitCube should draw the cube in its 
initial posiiton, viewing the kFront face along the KFrontBack 
axis, with the kUp face at the top of the cube, perpendicular 
to the view plane. The cul>e may be displayed with a 
perspective projection, from a reasonable distance, or from 
an orthographic projection from infinity. 

The final parameter provided to InitCube is ihe stepSize, 
used by the QuarterTurn and RotateCube calls in animating 
cube turns and rotations, The stepSize parameter specifies 
how granular the animations and rotations should be, with 
stepSize rotation steps constituting one full rotation. The 
value of stepSize will be a multiple of 4, so that quarter turns 
will contain an integral number of steps. 

The QuarterTurn routine is called to turn the 9 cubies on 
one face of the cube by 90 degrees relative to the rest of the 
cube. When QuarterTurn is called, you should rotate the 
specified face in the specified direction, animated in 
increments determined by stepSize. Any internal portions of 
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the culje not normally visible, but visible during live turn, 
should be displayed in a gray or black color of your choice. 

The RotateGube routine is called to rotate the entire 
cube, respectively. When RolateGube is called, you should 
rotate the entire cube about the specified eul>e axis in the 
specified direction. As multiple calls are made to RotateCube, 
the axes of rotation will become arbitrarily oriented with 
respect to the view vector, although the cube will remain 
centered in the cubeWindow. 

Finally, the TermCube routine will be called at the end tif 
the test, allowing you to clean up any memory you might 
have allocated before returning. There may be multiple test 
cases, each bracketed with an InitCube and a TermCube call. 

The commentary in the code for the Cube Axis describe 
the orientation used to perform clockwise and 
counterclockwise rotations of the cube. Similarly, the 
commentary for the Cube Face in the QuarterTum prototype 
describes the orientation for performing face quarter turns. If 
these explanations are not clear, please send me a note on 
the Challenge mailing list for clarification. 

Scoring will he based first on the quality of the accuracy 
of the display, and llie absence of tearing or other display 
anomalies. Among the accurate entries with acceptable 
display quality, the winner will be the solution requiring the 
least execution time. 

This will be a native PowerPC Challenge, using the 
Code Warrior Pro 5 environment. Solutions may be coded in 
C, C++, or Pascal, Solutions in Java wall also lx j accepted, but 
Java entries must be accompanied by a test driver that uses 
the interface provided in the problem statement. 

Tokee Months Aoo Winner 

Congratulations to Lanst Munter (Kanata. ON, Canada) 
for taking first place in the March Sum Of Powers Challenge, 
narrowly beating out the second place entry from Miklos 
Fazekas. You might recall that the March Challenge required 
you to find a set of terms which, added or subtracted 
together, formed a given positive integer. The terms were 
required to be integers raised to a power greater than I. 
Scoring was based on the number of terms used to form the 
result and on the amount of execution time used to calculate 
the solutions, with a penalty of 1 term per 100 milliseconds 
of execution lime. 

After the Challenge was published* several people on the 
Challenge mailing list pointed out that allowing .subtraction of 
powers of 2 made the problem trivial. Using the fact that 
(n+1)A2 - nA2 - 2n+l, one can form any odd number by 
subtracting the squares of two sequential integers, and any 
even number by adding or subtracting 1 to the squares 
forming an adjacent odd number. So I amended the problem 
statement to prohibit subtraction of squared terms. 


Instead of >lin£: around your house 

run your house with this. 

LevUon’s Touchscreen Decora Home Control center uses 
advanced graphics interface technology to take the mystery 
out of home automat ion .The 
result: total control over 
lighting. 1 leal i ng, appl i an ces 
and much more, all from a 
system as easy to use as a 
telephone. Simply plug the 
touchscreen into an electri¬ 
cal outlet and control 
Levttoil's acclaimed line of 
DHC switches, dimmers, 
receptacles, thermostats, 
and more. It's an automation 
system that’s as easy to add as it is to use. because it uses 
the existing electrical wiring as a command network without 
any special wiring. 









Decora Home Conlmls wtf) 
Touchscreen Contort Center are jusf 
one of the innovations in integrated 
Solutions for System Designers. 

For more information or the complete 
resource on CDWM r contact 
Levitan Integrated Solutions at 
(800) 877-0190 extension 789. 


© lOSS LcvllOrt Manufacturing On.. Jnc. ■ wvYw.lcvllon.wrn 
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Hanging around rift gallerlGS and 
museums could give an ordinary 
lighting Control delusions of grandeur. 

Fortunately, LevHon’s Monet 1 " , 

dimmer is no ordinary lighting 
control. It’s a work of art in itself, 
designed to associate with some of 
the best. Designed for use in show¬ 
rooms, galleries and museums, this 
architectural specification-grade 
dimmer is now stlowing in selected 
home environments as well. Pre¬ 
programmable scene control and 
all-digital circuitry can call up the 
right mood for romance or the best 
background for home theater. Most 
important, Monet's beauty is more 
than skin deep. IPs a direct descen¬ 
dant of the Levtton professional 
lighting controls proven in years of 
demanding commercial use. 




^integrated 

teuton^ Monel dimmers ate just oneof 
the innovations in integrated Solutions for 
System Qes&ers, Rr mere information 
or l/»e compare lesoarce cm CDflOH 
contactteutonIntegratedSGMwreaf 
(800) 8770190 extension 7S9. 
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Ernst’s entry starts by calculating the value of all integers 
raised to a power greater than 1 that fit into a signed long 
integer. The code offers an option to calculate this array at 
startup time, but for scoring purposes, this calculation was 
performed during the first SumOfPowers call. These 
calculated values arc used to to exhaustively look for a two- 
term solution, and then a three-term solution if no iwo-term 
solution is found. Finally, while Ernst conjectures that three 
terms are the most ever needed, a conjecture that was not 
dtsproven by my tests, he provides a recursive solution in the 
event no three-term answer is found, 

Miklos uses some facts from number theory to determine 
when a number can be written as the sum of two or three 
squares, and observes that every number can be written as 
the sum of four squares. He considers only the powers 2, 3, 
ami 5, noting that there are not many numbers raised to the 
power 7 that fit into a long integer. Thar assumption was 
costly, however, as his entry generated an extra term for 
numbers like 5054. Ernst formed 5054 as 4415^2 - Il A 7 t 
while Miklos formed it with an extra term: 71^2 + 3 A 2 + 2 A 2. 

1 tested Lite entries with 4330 lest eases, consisting of 10 
sequences of numbers of lengths between 10 and 1000, Ernst 
and Claes Wihlborg both solved the test cases by generating 
11880 total terms, but Ernst s entry took only 10% of the time 
that Claes' did. Miklos Pazekas' entry actually solved the test 
cases about 10% faster than Ernst's entry did, but generated 
enough extra terms to result in a slightly poorer score. The 
scores were dose enough that l considered code size as a tie¬ 
breaker, and Ernst’s entry was significantly more compact. 

The table below lists, for each of the solutions submitted, 
the total score, based bn the number of terms generated and 
total execution time; the execution time itself; the total terms 
generated for all test eases; and an error indicator, It also 
provides the code size, data size, and programming language 
used by each entry. As usual, the number in parentheses after 
the entrant's name is the total number of Challenge points 
earned in all Challenges prior to this one. 


Name 

Score 

Time 

Total Incorrect 

Code 

I>tiu 

Lmg 



(msec) 

Terms 

Cases 

Size 

Size 


Krnst Munter (567) 

11920.2 

4019 

nm> 

0 

5636 

5tUK 

C++ 

Miklos toukas 

1 19419 

3589 

11907 

0 

15480 

3015 

C++ 

Claes Wthlhorg U) 

12574.4 

49442 

11880 

0 

8472 

1.5.496 

C 

Kob .Shearer (43) 


138190 

13190 

0 

10380 

401 

C++ 

Jonathan Taytar <24)1 TTI 7 

2-1672 

14495 

0 

14772 

292 

C 

Bnidy l>u|p run 

17529,7 

4 lOfifl 

17119 

0 

116(1 

2.8 IM 

C++ 

.Stott Manor 

19951.7 mi72 

17760 

0 

1708 

16 

C 

S M 

I2HI50 

90996 

11903 

319 

2596 

HI 

C++ 

T.j. 

6A7K7.1 

5 

66787 

i 

436 

8 

c 

w it 




crash 

mi 

92 

c 


Top Contestants 

Listed here are the Top Contestants for the Programmer's 
Challenge, including everyone who has accumulated 10 or more 
points during the past two years. The numbers below include 
points awarded over the 24 most recent contests, including 
points earned by this month's entrants. 


Rank 

Name Points 

Rank 

Name Points 

L 

Munter, Eras! 

225 

10. 

Downs, Andrew 

12 

2. 

Saxton, Tom 

139 

IT 

Jones, Dennis 

12 

3^ 

Maurer, Sebastian 

91 

12 , 

Duga, Brady 

10 

4. 

Boring, Randy 

50 

13 . 

Fazekas, Miklos 

10 

5. 

Shearer, Rob 

41 

14. 

llewett. Kevin 

10 

6. 

Heilhaxk, JG 

43 

15. 

Murphy, ACC 

10 

7. 

Rieken, Willeke 

41 

Id. 

SeknguL, Jared 

10 

8. 

Taylor. Jonathan 

26 

17, 

Strout, Joe 

10 

9 . 

Brown. Pat 

20 





There are three ways to earn points: (1) scoring in the 
top 5 of any Challenge, (2) being the first person to find a 
bug in a published winning solution or, (3) being the first 
person to suggest a Challenge that 1 use. The points you can 
win are: 


1st place 20 points 

2nd place 10 points 

3rd place 7 points 

4th place 4 points 

5th place 2 points 

finding bug 2 points 

suggesting Challenge 2 points 


Here is Ernst’s winning Sum Of Powers solution: 

SumOfPowers.cp 
Copyright © 2000 
Ernst Munter 

r 

Pmfalan 

Given a number (the "result") between 0 ml 2*3Lfind a smallest set of terms which 
sum to the number A term is sign * % * y where y must be 2 or more and si^n may 
only lx* negative if y >= 3. 

Constraint 


All intermediate results, as terms are added or subtracted, must not overflow a 52-lsii 
signal integer variable 

Solution 

Basically by systematic trial and error. My conjecture is that all results tan be made 
with w> more than S terms, and a small number of functions are called in succession 
to try I term, 2-term and .Vierm sets. A fully exhaustive test of all 2 Ml cases ms not 
done, so my conjecture may be false. A final recursive function is provided to find sets 
larger than 3 terms, just in case. 
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Assumption 


SumOflVwersO will not tx iraUnf with maxTcnns < 3 This assumption may be 
overridden by setting 11 tKTKMAXIliRMS_j = L 

Array's of powers of x an- precalculated at startup lime (takes about 20 millisecs) it 
this is considered lo lx an unfair precakutetHm. the macro AUTOIN FI slumld be sci to 
0, and precalculation will be dune as part ol the first call lo SumOfftjwtxsO. 

Jibe solution was tested with Al TO I N I T set to zero - OiallcngeMcister Bob. I 

V 

^include (sidle.h> 

^include <stdlib,b) 

//define NDEBUC 
//include (assert,h> 

//include "SuwOfPowers.h th 

//Tum At IX UNIT on to save about 2Umsec in the first call. 

^define AUT01NTT 0 

// Turn Cl IliCKMAXTERMS ^ on to allow tests w ith maxlenns < 3 

//define CHECKMAXTliRHlO 0 

// Count number of powers of N which fit in a 31 bit long. 

on um I 

k2 = 46340, // = sqrt(2 A 3t ■ II 

kHigh - 1698, // = sumof ((2*31 - n = 5- 31 

kAli=k2 + kHigh L 

// = 4803^; actually slightly fewer locations will he used 
// because of entries like 2*6 -- i*3 onh one w ill be stored, 

h 


struct Entry I 

// Similar to struct IrttegerPmver hut trades v = Ixise A power 

unsigned long v; 
unsigned short beset 
tins ign e d short powe r: 

Entry 0 I I 

Entry [unsigned long vx.int b T int p): v{ vx) »ba.*se('b} .power (p) [ 1 


static ini Cmp(const void* a*const void* b) 

// Needed for quicksort 
Entry* pa^CEntry*)a; 

Entry* pfcHEntryQb; 
return pa->v - pb*>v: 

// simple delta works here because all values are positive longs 

1 


Search 

inline unsigned long* Search(long key.unsigned long efj* 
int length) 

I 

// Kinary search, returns the army element which is <- key 

unsigned long l“0,r*length-l.m.v; 

do | 

iupfl+r) »1; 
v^e[mj: 

if (key—v} return e+m: 
else if (key < v) r*n»-l; 
nine l^mU; 

I whl 1eO< D r); 
if {key < v) 
return e+r; 
else 

return e+m; 


struct ftiwerSoJvc 

static struct PowerSolve 

I 

// Collection of data and functions to solve SumOfPowcis 
int numAi J : // actual size (if array of all entries 

int rnmHigh; // actual size of array of high entries 

unsigned long vHigh[kHighl; 

Knt ry high [kHigh] : // sorted powers x A p with p>=3 
ms i gned 1 ong vAl 1 f kAll j; 

Knt ry a 11 [ kAl 1J; // sorted powers x A p with p>=2 


The jlOV^CSi connection on this 


QuickPort™ wallplate is more than 
150 times faster than your modem. 


Want the right infrastructure for 
tomorrow's information and enter-- 
tainment technologies? Invest in a 
Levi ton Structured Media™ system 
today* Our Xtreme ’ jack can move 
over i 00 floppy disks worth of data 
every second at speeds nearly 
20,000 times faster than the fastest 
modems, while QuickPort optical 
fiber connectors deliver giga-speed 
access to the future. No matter 
where technology takes you, your 
Leviton Structured Media system 
will always Look at home in your 
home, IDs part of Leviton's Decora 
system, the design standard for 
architectural-quality control and 
wiring devices* 






ons 


L&rtm Sfractatf Media' system 
are fust one of the innovations in 
Integrated Solutions for System 
Des^nere. For mote inkitwation 
or the compfete msowe on CD ROM, 
contact Leviton Integrated Solutions 
at {8001877-0190 extevjsrcvj 789. 
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Budding A CMHttfar Wrtd 


Why would 3nyOH6 want a power 
outlet that looks like this? 


Because it's a lot better than seeing 
red after an unexpected powerline 
surge turns your computer or 
home theater system into an 
expensive pile of junk. This Leviton 
Surge-Protected outlet is designed 
for applications where power 
quality is missionsritteal Why plug 
your home office or home theater 
into anything less? Especially when 
this professional-grade protection 
is also a genuine part of Leviton 
Decora, the design standard for 
architectural-quality control and 
wiring devices (yes, It's available in 
white and ivory along with fire- 
engine red)* 





£3 


^integrated 


■ ^ iewtafi Suigtettotecfcd cmiiets at? just 

one of the innovations in Integmed 
Solutions for System ftesgioCTS. 

€ '**#** Rir *rvbmTatfon or rhe oompiiefe 
, * resource on CDWM. contact 
tewten integrated So/uftons M 
^ - (800) 877-0190 extension 789, 

© 1&99 Leviton Msmrfncturmg Co.. Inc, ‘ lMtfW.tattltQn com 
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PowerSolveO (Created: I 
#endif 

void CreateO; 

bool l s Initial i zed 01 return nonAl 1; ] 

int Solve(unsigned long result*lniegerPower terme[J, 
long (naxTerms); 

void CopyPosit IvcTcrm(unsigned long* v.IntegerPower & ip) 

I 

// Copies an Entry into an IfltcgprFower 

Entry* p-fcall(v-vAllJ ; 

Ip. value**p ->base; 

Ip.power- >pover: 
ip,sign-1: 


void C op y N egai iv el'e no {unsigned long* v*IntegerPower b ip) 

Entry* p=fchighLv-vHigh]; 
ip.value^p->baEe: 
ip.power^p-> power: 

Ip, sign—1: 

I 


bool Eind2(unsigned long V,unsigned long* vQ, 
IntegerPower terms []) 


// lixliaustivt search for a pair of terms to match VI 
//Trying X+Y: 

unsigned long* saveV^vfl; 

unsigned long 1 vi=vG^Search(V/2.vAll t t+vO vAll); 
if (V = , v0+ i vl) 
i 

CopyPoflitiveTemf vO * terms [0 J); 
CopyPoaitiveTem(vl, terms [ 1 ] ]; 
return true; 

I 

do I 

long z ,delta-V-*vl; 
while ({z^'+tvO) <- delta) I 
if (z — delta) 

I 

Copy Post tiveTertnCvO * terms 10]): 

CopyPos! LiveTenntvl .temsflj) i 


return true: 

l 


Find2 


if (vK-vAll) break; 
delta=V xi 

while ((vDvAli) tA Uz-*-vl) >= delta)) I 
If (z “ delta) 

f 

CopyPositiveTermtvO,terms [0]}; 

CopyPositIveTermfvI t terns [1]); 
return true: 

J 

I 

I while (vO < saveV): 

//Trying X Y: 
vl-vHigh: 

unsigned long nurtrV+*vI; 
vO—Search (sum. vAl 1„ nttrnAl 1); 
unsigned long* endAll^vAIl+mimAll-1: 
unsIgned long * endBigh^vHighlnumKl gh l; 
for (;;) 

I 

if (£it«““v0) 

« 

CopyPos11iveTerm(vG t terms[0)): 
r.opyNf'guti veTenajvl ( terms [11); 
return true: 

l 

if tvl>=endHigh) break; 

SUEfi-Vi * l fvf; 


while UvG<endAIl) &A fv0 [ 1 ] O sum) ) 
v0++: 

I 

return false; 


JmdSuinl 

bool FindSuml (long V.unsigned long* vG, ImtegerPover termsf]) 

//Trying X + Y + Z 

unsigned 1eng * v 2 w yAll; 

unsigned long* v1 (^Search(V-*vG,vAI1,nu&AXl); 
for (: vG>”vAll; v(>-) 

I 

long dif£=V - *v 0 ; 

unsigned long* vX-Search{diff*vAIl*numAll); 

v2=vAIl; 

do { 

diff=V - *vG *vl; 

If CdiffCO) break: 

long z; 

while f[v2<=vl) && Uz=*v2> C diff)) 
v2++: 


if U = diff) 
t 

CopyPositiveTenu(v0.tarms[0]): 
CopyPositiveTerrafvl.terms[1]): 
Copy PositiveTem(v2.terms( 2] j; 
return true: 

) 

) while {—vi >- v2); 

I 

return false; 


FindDdUV 

bool FindDelta3[long V*IntegerPower termslJ) 

//Trying X-Y + Z 

for (unsigned long* vl^vHigh: vKvHlgMnnmHigh: v'++) 1 
unsigned long $unrV+ B vl: 
unsigned long* vO-Seareh{surn/2.vAl1<mmAl.1); 
long dlff“sum‘*vQ; 

unsigned long* v2-Scarch(dlff , vAli .riumAli); 

if (*v2 — diff) 

I 

CopyPosItiveTerm(vD,terms[0]): 

CopyItegativeTerm( vI.terms ft]): 

CopyPositiveTerifl[v2»r.ermn [2]}; 
return true; 

\ 

for (;;) 

l 

Vf>++; 

If fvOT^All+nuinAli) break; 
diff=sum**v0; 
tong z ; 

while ([v2>-vAl1) bb {(z“‘v2) > diffJ) 
v2“; 

if (k = diff) 

I 

CopyPositiveTernttvO, terms [0]); 

CopyNegatlveTermfvI.termu[11): 

CopyPoaitiveTermCv?,, luma [2] J; 
return true; 

I 


1 

return false; 


FmdFIrtaJ 
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Int. FindFinal [unsigned long V,unsigned long* vO* 
Integer Power termsI],io ng raaxT erm $1 

f 

// Subtracts The largest available term ami solves for the remainder 
// Always finds a (perhaps subnpUmal) set o# terms, 

// unless max'Terms is ion small 

CopyPositiveTenn(vD* terms[0]}: 

in t subTerms^SoIve(V * * vO * te nns+1.aaxTenns 1): 

If (sobTermfi} return subTerms+l; 
return 0; 

I 

I PS: 


high InHigh++I-EntryU. 1.3): 
long base: 

for (hase=2;base<-kHigh:base + +) 

( 

unsigned long v“base*base; 
unsigned long maxV^x7FFFFFFF/base: 
int power=2: 
for (:v<-maxV:J I 
v *= base; 
assert(nHigh<kHigh): 
hlghfnHigliH|^Entry(v,base, ++ power); 

I 

I 


inline int Compact(Entry e[J-const int numh) 

I 

// Compresses Entry army e|] hy removing duplicate entries (same v) 
int mimOufl; 

Entry* input**®! 

Entry* out* 4 *®: 

for (int 1-1 :i<numE:i++) 

I 

unsigned long v=(Hinput)-)v; 
if (v l" out>v) 

*++Out~ g input; 

I 

return l+out-«: 


Create 

//Hie following two timetions arc nut iulined, i'iiis b to control the 
// compiler’s (CtxicWarrinr Pm 5,3) inlining behaviour of the rest. 

void PawerSoive::Create() 

I 

// Constructs alL[J and high 11 arrays toy exhaustive enumeration 

int nAll-0; 

int riHlgW); 

// high 11 army starts with 1\3 

//The JUgJill array is constructed by mulliplying with base 


Compact // Sort and compress the high 11 array: 

qsort{Mgh*nHigh,sizeof (Entry) .Crop): 
nH f gh-Ctempact (high,nHigh): 


// Itic all11 array is constructed by additive accumulation of the 
// square terms and merging with the terms from the sorted higb[] 
unsigned long valued: 
uneigned long deita=5: 
unsigned long IastV=0: 

Entry* hp=higb; 

for (base=Z:base<"k2:base+*) 

I 

while ([hpCfbigft+rdilghn && (value >" hp->v)) 

f 

if (bp'>v 1= iastV) 

I 

asiert (nAlKkAll): 
vAll[nAll] = ls£t¥=hp')v: 
all EnAll-H-] fc *hp: 

I 

hp+f; 

I 

if (value I® lastY) 

I 

assert (nAlKkAIl); 
vAiltuAll]*l»stV“vfllue: 
all [nAll+bJ = Rnt ry (value,base,2}; 


It's Black and White 

Either you want a "Smart home", 
or a "Clapper" is enough... 

XTension 



Home automation for the Macintosh 


The most powerful home automation 
software on the planet 

If you like AppleScript, or you've never found a good reason, 
you'll love the cozy environment and rich features of XTension. 

Get infected ! Visit the website and join a large 
discussion list of avid and helpful users. 

shed.com 


Sand Hill Engineering Inc. email: sandhill@shed.com Phone: 407-349-5960 
Look for us at the MacWorld in New York 


♦ ♦ 












vAl 11 nAllJ^lastV-value; 
all inAii++]~Entry £value T base t 2); 
I 

value+=delta; 

delta+^s 

\ 

fur tint i~0;i<nHigh:H-+) 
vHighlil^highli].v: 

numHigh“aHlgh; 

numAll-nAll: 


Solve 

inr PoverSotve;: 

Solve(unsigned long result■IntegerPower terms[] .long raaxTenns) 
t 

// SolvrQ function solves for result by finding the fewest possible 
// terms, up to tnaxTcrm 

unsigned long* vfi w £narch(result * vAll.nuinAll): 

//A lLcrm R>iUt b found directly in the »ll]| array 

if (*v0 “ result) 
i 

CopyPositlveTemt vO. terms [Q\ J i 
return 1; 

I 

#if CH£CKMAXTliRMS_3 

if (maxTenns < 2) return 0; 
flendif 

//A 2'tcnn array may he a sum or difference of terms 

if (FindZ(result*v0 H terms)) return 2; 

#if GHEOTiAXTEHMS^l 

if (maxTerms i 3} return 0; 

/fend if 


// >term results titty he 
// all lx] + allfyl + aUfz| 

if (FindSum3(result t v0,terns)) return 3[ 

// or a|i{x| - hlgh(v] + all|z] 

// (very few results require ibis form) 

if (FindDeIta3{ result. t ertns)) return 3; 

// or ail[x] - highly 1 - highlzj 

// but this variation does not seem to lx: needed 

// Lengthy but not exhaustive tests have nul turned up a single 
// instance of result that could not lx* solved with three or fewer terms 
// but just in case there is a term fhar needs more terms, 

// FindFmalQ will provide a genrml solution 

return FlndFtnal(result,v0,terms.maxTerms); 

> 


SumGfPuwors 

long f* number of factors 7 SumOfP ewers ( 

long result a p terms need to sum bo this result 7 

IntegerPower toons f P P return terms sign^mrcgcr A power here 7 
long maxTerms f maximum number of terms allowed 7 

) I 

#if CHECKMAXTERMS_3 

if (maxTerms<“0) return 0; 
tfendii 

if (!PS,IsInitia1ized()) P$,Create()i 

return FS.SulveCtesul^teriiLS.cMxTeriafi) : 

I 
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'Ml be stuck in the 
heaviest traffic in New Y)rk City 
and loving every minute of it. 


This year tit Macworld, Apple is going to make it easier for till developers, big and small, to have a 
space as special as their ideas. Apple Developer Connection and MacTecb Magazine present 
"Developer Central®”an exhibit at Macworld that showcases developer tool/service companies 
developing for the Macintosh in the biggest possible way: Macworld will be held in New York City, 
J uly 18-21,2000, Check out the exhibits at the show and on the web at: wvw.devcentral.com 
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NETWORK 

MANAGEMENT 


By John C. Welch 

Contributing Editor, llene M. Hoffman 


DiskWarrior 2.0 


Reviewing the leader in 
Macintosh disk 
maintenance utilities 


Background 

DiskWarrior, from Alsoft Inc. 
<http://www.alsoft.com> is a disk repair 
utility for the Mac OS. It fixes directory 
damage and works on HFS and l IFS+ 
drives. Released at the Macworld Kxpo 
2000 in January, version 2 adds the a hi lily 
to prevent disk damage by preventing 
applications and utilities from writing to 
the disk in a way that would corrupt or 
damage the directory, 

Installation 

DiskWarrior has only two 
components, the application and the 
DiskWarrior extension. Although AI soft 
includes an installer, you can just drag 
the application to the desired location 
on a local hard drive, and drop the 
extension on the active System Folder. 
Once installed, reboot and you're done. 
If you don’t install the extension, the 
reboot is not needed. 

Using DiskWarrior 

Disk Warrior's interface is a model of 
simplicity and efficiency. As shown in 
Figure I , rhe main window has only two 
tabs, and a minimal number of controls. 
When compared to other utilities, such as 


Norton Utilities and Tech Tool Pro, DiskWarrior has a simplistic 
interface. There is no power user mode or hidden advanced 
controls. This is exactly what DiskWarrior is all about — it has 
one function in life, and that is to rebuild the directory structure 
on your hard drive. The Interface is also one of the most intuitive 
for a repair utility. DiskWarrior Lx even won a design award at 
die 1999 Apple Worldwide Developer Gwference. 


AHoft DiskWarrior 



✓ ^ Aurora 


^ MacQSX 


• Directory cvrot be retold because ih is ts the siartup disk 

• Directory Gemot be rebuilt because DisfcVarrwr resides: en 

this disk 

• This dish is alike OS Extended disk 

• Vhere (ATA Bus 0 Dev 0, 4} 



/ Disks \/PiskShielti™\ 


Please choose a disk from the 
menu below and click Rebuild. 


Figure 1. Main DiskWarrior Window. 


To use DiskWarrior, you select the drive you want to rebuild, 
and click on either the Graph or Rebuild buttons. When 
you select Graph, DiskWarrior analyzes your directory 
structure, and presents you with an easy to read picture of 
your directory* (See Figure 2.) 


John Welch <jwekJi#aer.mm> is the Mac and PC Administrator for APR tm , a weather and atmospheric science company 
in Cambridge. Mass, He has over fifteen years of experience at making computers work. His specialties are figuring out ways 
to make the Mac do what nobody thinks it can, and showing that the Mac Ls the superior administrative platform. 
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figure 2. Disk Warrior Drive Graph. 


The graph is a dear way of seeing whai your directory looks 
like, and it gives you a general idea of the state of your 
directory structure. Those who really understand how file 
systems and directory structures work may derive more 
meaning out of this than the less technically inclined. 1 just 
like the fact that a clean directory is indicated by a clean 
gradient, and the less clean the directory is, the dirtier the 
g rad iem becomes. 

Another good feature is the restriction on which drives 
you can rebuild. You cannot rebuild the drive you are booted 
from, or the drive from which Disk Warrior is running. This 
may seem to be a liability, but from a safety viewpoint, this 
makes perfect sense. Alsoft has chosen to allow you to repair 
only drives that can be dismounted when necessary, without 
potentially disrupting the rebuild process. This allows 
Disk Warrior to avoid making any permanent changes until 
Lite absolute last step, and also reduces the chances of 
crashing the repaired while the directory is rebuilt. 

If the drive you have selected is eligible for rebuilding, 
then dick rebuild to start the process. If an error occurs at 
any point before the actual replacement, rebuilding is halted. 
If Disk Warrior finds an error thaL must be fixed before it can 
accomplish the rebuild, you are asked to approve the repair 
or cancel the rebuild. If you cancel at any point, the disk is 
left untouched. After the Iasi step before replacement is 
completed, you are presented with a screen listing any 
damage found, as well as a general summary of your drive. 
There are two views, normal and detailed. The normal view 
has a generic description of the errors found, and is fairly 
useful for most users, while the Detail view covers specific 
problems found, (figure 3 .) 



Figure 51 General View of / Hsk Wani< j r AY/* >rt . 

[f you need to know exactly which files/.structure* have a 
problem, click on the Details huLlon to see a list of every 
problem, and exaeUy what was found, This is an invaluable tool 
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a single application 
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Web Server 
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eCommerce Server 
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WS4D Pricing; 

WS4D/eCommerce Single Store.....$495 

WS4D/eCommerce Unlimited Stores..$795 
WS4D/eCommerce Developer...$995 


• Supports AuthorizeNet or E-xact for real time 
credit card authorization 

• Easily publish products from your StoreFront 
directly to search engines (or Sherlock). 
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• Auto Prints / Creates PDF's, Product Actions. 
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for troubleshooting repeated drive problems. (Figure 4.) A 
complete lisi of potential problems and explanations are 
included on the Disk Warrior PDF manual on the CD, 


MscOSX 



f igure 4 Detailed View ojDisbWarrior Rej?ot1. 

Another interesting option for Disk Warrior is the preview 
ability, I Ills button has Disk Warrior create a duplicate disk 
directory for the selected drive, and shows die drive as it will 
appear when the directory' is rebuilt, DiskWanior warns you that 
the lx )th the current and preview directories will be kicked, and 
not to unmount either disk, (Figure, 5, i 



The original disk and the preview disk now 
appear on the desktop. Both disks are locked 
to prevent alteration during preview* 

The Finder will be brought to the front oo that you may 
view the disks. When finished, please return to 
DUkWerrior and click either "Replace" or "Cancel.” 
Please do not remove either disk from the desktop. 


[ cancel j 


Continue 


Figure % Preview Disk Dialog. 


When you dick on Continue, two drive icons appear. The 
non ml icon is your drive as it currently exists, and the preview icon, 
which is your drive as it will lx.* after rebuilding. ( Figure 6.) 


■ '^ai. 


MacOSX 


figure 6. Preview mid original disk on desktop. 

This is an invaluable function if you are trying to rescue 
a lost file, as you can compare both versions, and see if the 
rebuild will actually rescue the file* I have found that if the 
file is gone due to directory errors, Disk Warrior will rescue it 
almost consistently. If the file is gone because it was deleted, 
then DiskWarrior won't rescue it. If you need to rescue a file, 
then I recommend using a utility specifically designed for 
that purpose. 

Once you have seen details, and previewed the drive, 
you can either cancel or continue with the rebuild. If you 
click Cancel, nothing happens, and your disk is unmodified* 
fi you click Replace, then the drive is unmounted, and the 
directory is replaced. This step gave me my only moment of 
worry with Disk Warrior, as when the progress bar is about 
one-half inch from the end, it may pauses for a while, 
depending on the machine. The first time this happened, ! 
thought "Oh great, it crashed. I’m dead. 14 I rebooted the Mac 
Irani the DiskWanior CD, and sure enough, 1 got all kinds of 
funky messages, including the dreaded: l caret deal with this 
drive, initialize it?” 1 decided to not initialize it, and give 
Disk Warrior another chance. In this case, once the 
^supposed> crash happened, I sighed, and went to get more 
coffee, figuring l had a long night ahead. When I returned, 
lo and behold, the progress bar was done, and everything 
looked fine, i ran Disk Warrior again, and waited* Sure 
enough, about two minutes alter it paused, it finished, and 
my drive was fine. This is both good and bad. Good, because 
it was able to fix the damage caused by my premature reboot 
of the Mac. Had, because 1 did not need that near coronary 
that the pause gave me, nor did 1 need to reboot the first 
time, in any case, when Disk Warrior pauses, don't reboot 
until you get a completion message, an error message, or 
wail about 20 minutes. (The larger the hard drive, the longer 
the paused After using DiskWanior version from 1,0 to 2,0 
on 30 Macs I have only found two cases where DiskWanior 
threw up its hands and gave up. In tile first case, die drive s 
head had crashed, ami in the second case, Disk Warrior 
would luck up or give up. As ii turned out i had a bad DIMM, 
which caused the problems* In either case* DiskWanior 
caused no harm, and left me no worse than I was before, 
unlike some oilier utility packages which I've used. 

DiskShield 

The second Lab is a new feature in version 2.0, 
DiskShield. DiskShield is designed to prevent you from 
incurring directory damage in the first place. This is what the 
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Disk Warrior extension controls, and this tab. (in Figure 7) 
allows you to sot DiskShlekFs options. 



f igure 7. DiskShidd Options 

The first control Ls the actual switch for Disks hi eld. by 
default, after the extension is loaded, DiskShidd is turned 
oil I appreciate that Alsoft allows me to choose whether to 
turn the extension on, as opposed to most vendors, which 
automatically turn extensions on. Once you turn DiskShidd 
on. the other options come to life. The notification is fairly 
self-explanatory. You can decide how you want to be 
notified at which level of severity, either by an alert dialog, 
or flushing the Apple Menu. (The alert is a nicer option for 
MacOS 9 with those nice, unobtrusive windoid dialog boxes* 
) 1 was able to test this out, when installed the latest beta of 
AOk instant Menu (AIM). As the install finished, DiskShidd 
suddenly popped a warning about an attempt being made to 
write to the directory in an unsafe manner, and that I should 
immediately run Disk Warrior on my drive. What was nice 
was that the damage never occurred, and my directory 
remained clean. DiskShidd had prevented a bad write to 
disk, but SeL the write happen, only in a safer manner, 

Tiie next set of controls concerns speed issues. Since 
DiskShidd checks every single w rite to your disk, if you are 
about to download a lot of files, (say a couple of hundred or 
more), you might see a speed penalty. So by selecting Bulk 
file operations are faster, you tell DiskShidd to not 
monitor these types of writes, and thereby avoid any speed 
penalty. You can also turn off DiskShidd for individual 
applications, in Figure 5 1 have turned off DiskShidd to run 
an AppleScript that copies my web site to disk. This copy 
involves over 3,000 files, so I don't want every write 
monitored for that application. 

DiskShidd is an extension, so, the standard possibilities 
for conflicts exist. As of this writing* I am working with Alsoft 
Tech support to resolve a conflict that manifests itself as a 


Type 10 error. We have determined that the DiskWarrior 
extension by itself, or with the standard MacOS 9 extension 
set is not the culprit, so it is a third party extension conflict. 
This should not reflect poorly on DiskWarrior as much as act 
as a reminder that extensions should be used as sparingly as 
possible. The DiskWarrior PDF Manual also includes a 
section on troubleshooting extension conflicts, 

DiskWarrior Functionality 

As p rev it >usl y m en I i t >ned. Disk Wa rri t >r dt ies nc it pa t cl i or 
repair your disk directory, but rebuilds it. This is an important 
distinction over Norton and TechTool Pro, which normally 
apply fixes and patches to the damage in a directory, 
(although TechTool Fro version 3 0 has an option for this type 
of directory 5 ' repair). In contrast to repairing an existing 
structure, DiskWarrior analyzes your drive, and the files cm it, 
and creates a completely new optimized directory. By 
replacing the old directory in its entirety, a lot of errors that 
can accumulate even with applied repairs, are completely 
fixed. {The analogy here is the difference between dropping 
a new engine into your car, and rebuilding the existing one. 
Both will work, but only the new engine is going to allow you 
to effectively start at zero with regard to mileage, ) This also 
means that every dine you run DiskWarrior, you get a brand 
new directory, which is as close to a brand new drive format 
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you can get without actually reformatting. The list of what 
Disk Warrior will fix is impressive, DiskWarrior run on a 
regular basis lias been excellent for preventative 
maintenance* The directory rebuild also optimizes the 
directory structure, so that you should see some speed 
increase alter the rebuild also. 1 did see some speed increase, 
but, 1 have about 45,000 files and folders on my main drive, 
so your mileage may vary. DiskWarrior is also seriptable, so 
you can use AppleScript to automate the rebuilding of drives, 
I haven’t found a need for it, but the fact that it is available is 
an indication of the thought that went into the product, 

DLSKStnF.il> FirNcnoNAiJTY 

According to Susan Starnes, AI so ft's marketing 
representative, DiskShield does iwo things to save you from 
damaging your drive. The first is DiskShield checks what is 
going to be written and how the write is supposed to occur, 
by checking the file system calls the application Is making, if 
tiie write is safe, then it proceeds. If the write is not safe, then 
you are alerted as to its severity, and warned that you should 
run DiskWarrior as soon as possible to check for damage. In 
my one, (admittedly not a large sample size) experience with 
this, the write was allowed to occur, but no damage 
happened so DiskShield was doing its (oh quite well. The 
second function of DiskShield involves the disk cache. The 
disk cache is a space in RAM that holds frequently accessed 
data. Normally, this is used primarily for data coming from the 
disk, or "reads." However, it can also be used for w rites, and 


RCI AUTOMATION 

RCI Automation offers home automation solutions that meet your present 
and future needs. We also install the products we sell so we know which 
products work well together, and which ones don't. 

We will help you automate the following systems of your home: 

• Lighting 

• Irrigation 

• Heating and Cooling 

• Com muni cat ion s 

• Audio/Vrdeo 

by providing you with expert pre-safes advice, product sales, installation 
and configuration guidance, and continuing technical support. 

Visit our web site for ideas of whot you can automate in your home, and 
take a look at the unique products that we offer. 

E-Mail: rciautomation@compuserve.com 
Voice 619/857-4268, Fax 603/251-6376 
http://ourworld.compuserve.com/homepages/rciautomation 


can speed those up as well. If there is a crash with data still 
waiting to be written in the cache, particularly directory data, 
(i.e. creating a new folder, renaming a folder, etc), then disk 
damage can occur if the cache is not flushed cleanly. 
DiskShield, If ir detects a cached directory write, forces the 
write to occur immediately, rather than at idle lime as is 
normal. This ensures that directory structure changes are 
made as quickly as possible, thereby lessening the chance for 
directory damage in the case of a crash. 

As 1 pointed out earlier, there is a potential for 
slowdowns here, especially in the case of large numbers of 
files being transferred. In reality, I haven't seen it yet, and that 
includes a 9000+ file transfer I did via FTP just to beat on 
DiskWarrior. If you think uhout it, unless you are transferring 
from a computer with a Gigabit network interface to your 
Mac, which also has a Gigabit interface, your file system is 
operating at much higher speeds than the network is capable 
of running. In that case, any slowdowns from DiskShield 
aren't even going to show up. If you are doing large transfers 
between drives on an Ultra-Wide SCSI card, then you may see 
a slowdown. In a test with a Beige G3/300 server, running 
Mac OS 9. AppleSharelP 6.3, and using an Adapter 3940UW 
dual-channel card, transferring files between two mirrored 
drive sets was so close to the speed without DiskShield, that 
realistically, there was no difference DiskShield requires an 
extension to operate, so conflicts can, and in my case, do 
happen, (hi my case, the conflict teas with the net Octopus 
>5.2 agent, ami the Vi rex 6X control panel.) I must also say 
that AI suit’s technical support staff has been absolutely 
outstanding in their efforts to help me resolve this problem. 
No finger pointing, just excellent help. The way I see it. by 
preventing a bad install from damaging my disk, DiskShield 
made its case better than any amount of press ever will. 

Conclusion 

With this latest release of DiskWarrior, AI soft has 
improved on not only the track record of a truly outstanding 
product, but also the company’s overall track record. 
Although I could do without the pause during the last part of 
the rebuild, its a niggling complaint, and the only one I've 
had since version 1.0. DiskShield is a welcome addition to 
DiskWarrior, and has given me real-world proof of its value 
as well. A nice touch with version 2d) is the inclusion, of 
PlusOptimrzer for free, so that not only can you rebuild your 
drive’s directory structure, but also you can optimize the files 
on that drive in the same session. Just one of those little 
polishes that place Alsoft at the top of any group of Mac 
software companies. I would also like to note that in addition 
to superb technical support, Alsoft’s Marketing Director is 
one of the most technically savvy individuals I have ever met 
in that type of position. To sum ii up: if you own a hard 
drive, you need DiskWarrior. If l had to pick one disk utility, 
forsaking all others, this would be the one. For more 
information, visit iheir web site at <http://www.Alsoft.com/>, 
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space as special as their ideas. Apple Developer Connection and MacTecb Magazine present 
“Net Innovators” an exhibit at MACWORLD that showcases Internet texis, products and services 
for the Macintosh. MACWORLD takes place in New York City, July 18-21,2000. Check out the 
exhibits at the show and on die web at: www.netinnovators.com 
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FROM THE 
FACTORY FLOOR 


By Quinn The Eskimo!" and Richard Atwell, ©2000 by Metro works, Inc., all rights resorted 


A Chat with Quinn “The Eskimo!” 


This months Factory Floor Interview brings us back to Apple 
again for a visit with Quinn “The Eskimo!", co-creator of Internet 
Gonfig, Quinn works in Developer Technical Support and took 
time out from helping us all write tetter axle to sit down and 
talk ateui his world. 

Richard: Who are you? 

Quinn: All, a deeply metaphysical question, but lor the moment 
Ml held it literally t am Quinn 'The Eskimo!” I do have a first 
name but i haven’t used it for about 20 years. The epithet 
“The Eskimo!" is from an old Hob Dylan song, since covered 
by Manfred Mann amongst others. Listen to the words 
closely; it's a lot of fun. 

Richard: Where are you from? 

Quinn: Another deep question, 1 was tern in Kenya and my 
folks arc English. I grew up in Perth, Western Australia, and 
I'm now living in California, Perth is a big city (more than a 
million people) but by American standards it s my isolated. 
My friends and I often say that the definition of isolated is 
that if you 1 ravel for a thousand kilometers in any direction 
from Perth, the nearest big dry is... Perth, because of this 
isolation, the Mac developers are a close knit group, 

I was very active in two areas of the community; namely, Mac 
developers and university support staff. There’s not a lot of 
shrink-wrapped software development in Perth, so there was 
a huge overlap between the groups, 

Richard: What did you do after school? 

Quinn: My first job after graduating was at the Computer Science 
department at The University of Western Australia 
<htlp://www.cs.uwa.edutu/>._ 1 spent a third of my time 
running the network, another third running the student 
Macintosh lateratory, and the rest programming, li was a 
great place to learn about the Macintosh, I handled both the 
user and developer side of things. And writing lab 
management tools is an excellent introduction to the 
underbelly of Mae OS! 


Richard: Wlial are your responsibilities in Developer 
Technical Support (PTS)? 

Quinn Since late 1995 Eve teen working at Apple in the 
Networking, Communications and Hardware group of DTS* 
During the day I answer develu|xr questions, code samples 
and write rechnotes, I also review' documentation, lirehght, 
provide feedback to engineering, go to kitchens, and so on. 
It s a very diverse job. which keeps me from getting bored. I 
would find spending all day copped up in my office coding 
for a single project a drag 

When I joined DT5 I was cast into the role of "Open Transport 
guy", somewhat harrowing given that l had never 
programmed for either MacTCP or OT tefore. Hey, I ktww 
people who had programmed for MacTCP, but l didn’t actually 
do if myself! Since then I've supported OT through its (and 
Apple's) ups and downs, OT work is Mill a large chunk of my 
job. although I also support mass storage, external file 
systems, virtual memory, driver services, and so on. 

Right now my day job is to support these existing 
technologies while gearing up for Mac OS X. In my spare 
time J m working on a cool little tool called System holder! Tiff 
<ftp:A lifTC[Uinn.ediidna,kLau/Olhers/( v )uinn/Devd<>pmenr/> 

. Actually. I've teen distracted from that by "MoreOSL", a C 
framework for implementing AppleScriptability in an 
application. It's a much harder job than I thought, so the code 
will eventually end up as a DTS sample. 

Richard: You’re famous for being one of the co-creators of 
Internet Config, 

Quinn: Mostly Fin famous lor being friends willi Peter N. Lewis, 
Peter, myself, and a mutual Friend (Marcus Jager), were all 
friends in high school and then we went on to university 
together. After finishing our degrees, Peter started working on 
his shareware business (at first after-hours, and now Full-time 
<http://www.stairways.com/>) and I helped him out with 
miscellanea — like keeping Iris user interface honest, editing 
die documentation, and so on — in my spare time* 
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'flie only majorcolla1x>nHbn tx-lween Peter and I was through 
Internet Config <http://www.qLi Inn,echidna.sd.au/Qutnn/Config/>. 
Him project has a long history a] I Lo itself anti I still have 
trouble groking that I've been working on it for over six years! 
It’s great to make something that helps lx)th users and 
developers. Another fortuitous ouleome of the Internet Qrfig 
project was that ii raised my visibility sufficiently, so much so 
that Apple decided to hire me into D'I'S. 

Richard: They say that necessity is the mother of 
invention. Was Internet Config conceived that way? 

Quinn: Yes. It all started w ith a discussion on comp,sy.s.mac,comi« 
sc y\ i letime in mid -1994. Iiasieally every<>ne was sk k c >f having 
to enter the same Internet preferences into a gazillion (yes, that 
is the technical term!) Internet applications. This was 
partial lady irksome for me because I didn 't use Netscape ax 
my web browser. In the days before Internet Explorer I here 
was MacWeb and I got really tired of I laving to change the 
default preferences in every application that warned to launch 
URLs, and ilien reapply the change on each new machine and 
also every time 1 reinstalled system software. 

The newsgroup discussion quickly got out of hand (as they 
are apt to do) so Peter N. Lewis created a mailing list and lie 
unilaterally subscriixrd all participants to the mailing list. The 
little we switched everyone over was midday, Oz time, so the 
VS folks got a shock when Lhey showed up to work the next 
day and found hundreds of messages from a mailing list to 
which they'd never subscribed! Fortunately we didn't get too 
many Hame-o-grams. 

The recipient list reads like a Wlufs Who of early Mac 
Internet types. With so much Latent, there were IxhjikI to be 
some contentious Issues. 


Should tite system support multiple users? 

Should the system support layered preferences (e.g. a user 
layer above an application layer above a global layer)? 
Should lire system be an extension? 

Peter and 1 had a strong opinion on all of these topics. We 
wanted to keep it simple white allowing for future 
expansion, so we answered no, no, and yes to the alxtve 
questions. To cut short the discussion, we designed a 
straw man API and posted it to the list, After incorporating 
some feedback, we set off to implement the APE 

The actual coding of the* extension took very little time, 
probably a week or so of part-time work. The original plan 
was for Peter and f to write the extension while another 
developer did the user interlace. After months of waiting for 
a Lit, we eventually caved in and wrote that as well. 

It's interesting to examine the tore design decisions w ith six 
years of hindsight. 

Hie lack of multiple user support was a problem, but t 
eventually retrofitted \seLs" into 1C 2.0 (Mac OS 8,S). 
Afterwards. Apple introduced Multiple Users (Mac OS 9*0) 
which provided another solution to this problem. 

I still believe that layered preferences are too hard lor users 
to understand and lielieve we made the right choice by not 
including them in 1C 

I'm very happy that we shipped IC as an extension rather 
than a statically linked library. It has allowed us to update the 
system easily; a facility we've used extensively over the years. 

I’m very disappointed by the fad that 1 failed to think dearly 
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alxmi international Issues in the original IC design. For example, 
we should have had a dear policy regarding intemational- 
friendly text in preferences like the email signature. 

lair a lurther read about the rationale and die implementation 
details of IC 1.0, read my article in develop magazine. 

<http://developer.appie.coni/dev/rechsupport/develop/issue23/quinn.htril> 

Richard: How difficult was it to get authors of shareware 
networking programs to adopt IC? 

Quinn: With a lew exceptions, convincing developers to adopt 
IC was surprisingly easy. Mind you, we made numerous 
design decisions dial smoothed the path. Our basic goal was 
to give developers no excuse to ignore the technology. 

We Started with a critical mass ot Internet devek>[)crs from 
the mailing list on our side. 

1C was simple enough for both users and developers to 
understand. 

K . was usable from all the popular development environments. 
IC APIs could lie used with or without having the Internet 
Config Extension installed. 

1C sup|K)rtcd System 6, In fact, the first version without 
System 6 support (IC 2.0) was released in June 199K! 

We offered individual support to key players to promote 
adoption. 

Richard: Why did you choose to release IC into the 
public domain? 

Quinn IC source code was put into die public domain so that, 
if Peter anil I were killed in a 747 accident over the Pacific 
on the way to WWDC. another developer could pick up the 
development. This also helped to alleviate any fears of the 
technology lx-ing orphaned. 

Richard: What have been the most recent Internet 
Config developments? 

Quinn: The big news for Internet Config is its 
integration into Carbon. Universal interfaces now 
includes “lnternetConfig.h"! On traditional Mac OS, 
CarbonLib 1.0.2 provides glue that calls through to the 
existing Internet Config Extension. On Mac OS X, 
Apple will provide a re-implementation of the API 
based on CFPreferences. This gets me off the hook for 
future Internet Config development, which is a relief. 

It was fun while it lasted, but our mission was ahmys 
to get Apple to adopt the technology. 

Richard: Now that IC is part of Carbon, what will 
happen to the IC Programmer’s Kit? Is there a 
new version planned? 


Quinn: Before Apple decided to adopt IC as part of 
Carbon, I had finished the core code for IC 2.5, 
which included full Carbon support for traditional 
Mac OS (and some limited support on Mac OS X). 
Given Apple’s decision to support IC in Carbon, I’ve 
had to revise my plan. 

I do intend to ship a new IC that fits in with this 
new world order and will probably still call it 2.5. 
In the meantime, 1 would recommend that 
developers just use the interfaces and libraries from 
UI 3-3-1. 

Richard: Can you teU us what about anything new 
regarding networking? 

Quinn: In the networking space, Apple has made 
much progress over the last year but much of it is 
hard to see. Open Transport 2.5 includes many 
internal changes that should allow us to deliver new 
features more quickly. 

I he next year promises to be very interesting for 
Apple followers. It's time for Mac OS X to start 
delivering on its promises so ii should be exciting 
to watch and participate in. 

Richard: I know you’re a staunch Pascal 
developer. IIow strong is the Pascal movement 
in the Mac developer community these days? 

Quinn: 1 wish that I had some hard numbers on this, 
but alas I don’t. Moreover. I’m not really at large in 
llte Mac development community these days (DTS 
keeps me plenty busy witli my real job!) so I don’t 
even have a rough feeling for this. I can tell you 
that I’m regularly called in to consult on Pascal 
issues for Apple, for example, I’ve helped a number 
of significant developers move lheir large legacy 
Pascal source bases to Carbon. 

Richard: How much longer can we expect Apple 
to provide support in their APIs? 

Quinn: As a current employee, I can’t comment on the 
future oi the Pascal interfaces. I can say that the current 
situation for Pascal interfaces is pretty good. Apple 
creates the Universal Interfaces from an internal 
representation (something that looks like a C header 
file, but isn’t) using a custom tool. This tool outputs C, 
Kez, Asm, and Pascal headers automatically. As long as 
this system is maintained, Pascal Interfaces can lx* 
easily generated by flipping a switch. qq 
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by Jeff Giles <online@mactecb.com> 


Relational Databases for Mac OS X Server 


Earlier this year we covered 
WebObjeers, hut we didn't go into detail 
about the database solutions available to 
use with it. This month we are going to 
cover relational databases which run 
under Mac OS X Server. I should 
mention up front, though, that it's 
perfectly possible, and quite common, 
to run your application server and 
database on different machines, under 
different platforms. There can be 
convenience and speed advantages to 
running everything on one machine, bin 
as your website scales up to higher 
capacities. youTe certain to reach a 
point where you need to run multiple 
copies of your application server, on 
multiple machines, and modern 
databases are designed with the 
expectation that they will be accessed 
simultaneously from multiple locations. 
Of course, backing a WebObjects 
application is only one use for a 
database, and you may have other 
reasons for wanting a solution that you 
can run locally. 

Database Adaptors 

1 should also explain a little bit 
about the way that WebObjects 
interfaces with databases. They 
communicate through an EO Adapt or. 
which usually takes the form of a shared 
library. The adaptor and the rest of the 
Enterprise Objects Framework (EOF) 
take care of most of the details of this 
communication, so that the developer 
doesn't have to worry about differences 
between the databases or between the 
dialects of SQL that they support. (It’s 
even possible to develop adaptors to 


interface to non-relational databases, and Apple supplies an 
example Flat File Adaptor which lets you access formatted 
text files as though they were database tables.) Apple 
supplies EOAdaptors for Oracle, Sybase, Informix, and 
ODBC, although not for all platforms on which WebObjects 
runs, There are third-party adaptors available for many 
others—all of the databases well cover below have adaptors 
available, Note lliat there is currently no ODBC EO Adaptor 
available for Mac OS X Server, because the ODBC libraries 
aren't available for the platform, and neither are drivers for 
any of the databases you may wish to access by ODBC, 
(ODBC, or Open Database Connectivity, is a technology 
invented by Microsoft, and attempts to allow you to access 
different databases via a common API, with support for 
different databases being supplied by ODBC drivers. Us goal 
is analogous to that of the EOF, although it is functionally 
quite different.) Third parties have announced that they plan 
to bring ODBC support to Mae OS X, but il hasn't arrived yet, 

WebObjects 4.5 Developer Documentation 

<http;//developerappie.com/techpubs/webobjects/webobjects.html> 
Mac ODBC Guide 

<http://www.gafvan,unsw.edu.au/gerham/macsos/ 
MacQD8C/index.hTml> 


SQL-based Databases 

You have three main choices if you do want an SQL-based 
database which runs on Mac OS X Server itselh FrontBasc, 
OpenIiase T ami MySQL. Each has its advantages and 
disadvantages, and the best choice will depend on your situation. 

Open Base has had a long history on the OpenStep 
platform, and was written specifically to run there. It comes 
with graphical administration tools, and has a few features, 
such as the ability to notify applications when data changes 
and integration with REALbasic, which are not commonly 
found in other databases, Mac OS X Server ships with 
OpenBase Lite, a free version which allows you to work with 
the included sample databases, but this version lacks 
administration tools and isn't really appropriate for 
development work. There is also a fully functional, time- 
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limited demonstration version which you can download from 
the Open Base website. This gives you ample opportunity to 
try out Open Base for yourself, but for actual development or 
deployment you need to obtain a commercial license. Also 
note that Open Base is available for Windows NT and Solaris, 
in addition to Mac OS X Server, so iL is a good match for 
heterogeneous environments in which multiple operating 
systems are used, or migration from one to another is likely. 

OpenBase International, Ltd. 

<http://www.openbase.com/> 

From Rase, produced by Frontline Software of Denmark, 
is a cross-platform database written in C, It runs on a variety 
of platforms, including Mat OS X Server, Windows NT, 
Solaris, and Linux. Like OpenRuse, it includes graphical 
administration tools, allowing you to create and manage 
databases easily, (Of course, you can also do this using SQL 
directly.) One key attraction of FrontBnse is its flexible 
licensing terms. There are a number of different levels, based 
on different degrees of support and different features, such 
as bulk import tools and the ability to lock tables in memory. 
The lowest level is free, and is fully functional but lacks 
security features. This basic version is more than adequate 
for development work, and can even be used fur deployment 
if you keep it safely behind a firewalk 

Frontline Software 

<http://www.frontline-software.dk/> 

The third choice is the open source database MySQL (ft's 
open source, but there is a fee for some types of commercial 
usage.) MySQL is very' popular in the Linux community, and 
An jo Krank has created a set of patches which allows ir to run 
under Mac OS X Server Actually, recent versions of MySQL will 
compile and run without patching, although you need a 
pthreads compatibility library which he provides. (He has also 
developed an EOAdaptor for MySQL, and a Perl DB1 driver for 
Front Rase.) MySQL’s claim to fame, other than being open 
source, is that it is extremely fast The reason for its speed is, in 
part, dial it lacks certain key database features, such as 
tnmsactionality and rollback. These are major capabilities to do 
without, and in fact technically disqualify it from Ix^ing a 
relational database, but if you can live with its limitations then it 
ran be an excellent choice for many applications. Due to its 
heritage, you'll have to survive without built-in graphical 
management tools, but in the database arena it is often 
convenient to manage your database directly via SQL. because it 
allows you to easily save and reuse scripts fur common tasks. 

MySQL 

<http://www. mysql.com/> 

MySQL for Mac OS X Server 

<http://www.prnet.de/RegEx/mysql.htm!> 


ORACI.E 

As l mentioned before, you can certainly run your 
database on another platform, even if you are developing for 
Mac OS X Server. One setup you may want to consider is 
running Oracle#! under Linux, (This would unfortunately 
mean running it on an Intel box—Oracle runs neither on Mac 
OS X Server, nor on Linux PPG. Given that Larry Ellison siLs 
on Apple’s board of directors, there is some hope that this 
situation may improve in the future, A Darwin version could 
do amazing things for the platform.) Neither Oracle nor Linux 
is trivial to administer, but I’ve heard it argued pretty 
convincingly that you should use Oracle from the beginning, 
even if you thing it’s more database than you need. The 
argument goes that if you are running a database-backed 
website, you wall eventually need Oracle, and your Me will 
be easier if you don't have to deal with migrating to, and 
learning to administer, a new database just when your 
business is taking off and you're exceeding your capacity, 
(It’s also true that both Linux and Oracle experience looks 
good on a resume these days.) Oracle is by far the most 
widely used database on the planet, and it has an excellent 
reputation for performance and reliability, although it’s 
almost impossible to get hard numbers to quantify this. 
Personal experience has led me to believe that commercial 
databases all perform similarly when it comes to raw retrieval 
speed, although Oracle's unique approach to concurrency 
control and locking should give it an advantage when many 
processes are writing to the database at the same time. (In a 
nutshell, readers and writers rarely interfere with one 
another,) Oracle also has a very well thought out approach 
to backup management, and if your database fails you can 
often recover all the way up to the very last transaction 
committed. While making your decision, you should be 
aware that Oracle is extremely expensive, and although its 
licensing scheme is difficult to decipher, it does appear to be 
free for development use. If you plan on running a business 
which will depend on your database, you should give Oracle 
serious consideration. For extremely high-capacity 
deployments you will probably want Lo run Oracle on Solaris, 
and migrating from Linux to Solaris will be much easier than 
migrating from a different database architecture. (Oracle has 
been very good about making its database operate almost 
identically on all supported platforms.) 

Oracle for Linux 

<http://platforms.oradexom/linux/> 

Once you've committed to a database, check out the 
MaeTech Online web pages at <http://www.mactedi.com/onlme/>, 

E3 


94 


MalTech Online 


MacTech * June 2000 









Ahead of the times for over 15 years, 
MACWORLD Conference & Expo has 
been the only arena where: 

» Industry leaders, Mac professionals, 
and all levels of Mac users gather to 
discuss the latest products, services 
and solutions for the Mac Community 





xpo.com 


1‘800-645-iXP0 


Owned and Managed by 

• IDG 

WORLD EXPO 

Flagship Sponsor 


One-stop Shopping! 

® Featuring 400+ exhibiting companies! 


@ Awards and competitions! 


® Flands-on demonstrations! 


@ Prizes, drawings, and giveaways! 


Cutting-edge 
Educational Sessions! 


® MACWORLD Conference & Expo 
is a comprehensive event 
featuring interactive workshops, 
the MACWORLD Users 
and MACWORL D/Pro Conte rent 
programs, the Keynote address 
other special presentations 


Conference and 
Workshop Programs 

Inly 18 - 21,2000 


ReoEstemy Mrm 
for special savings! 


Exposition 

July 19 - 21.2000 


Macworld MacBuyfcom MacCentral.com MacWEEK.com NlMrllCOIIt 















WEB 

TECHNOLOGIES 


By Danny Swarzman 


Solitaire in JavaScript 


One approach to 
structuring code with 
initializers and lambda 
expressions 

Preface 

This article introduces JavaScript. 1 
focus on a failure of the language that gels 
very little mention in lxx>ks: the ability to 
use a function definition as an expression, 
This article provides an example of how 
such expressions can he used to produce 
a legible program. 

I hope Lo provide a hint of JavaScript's 
power to create an interesting user 
experience under Lx browsers, by 
presenting a sample program that creates a 
Peg Solitaire game in a web page. 

Getting started with JavaScript is 
easy. All you need is a text editor and a 
browser, but first, let s review some core 
JavaScript concepts. 


* Inside an HTML tag as the value of an attribute such as 
onMouseGver, onMauseOul etc. This code is interpreted when 
the event occurs. 

• As the value of the HREF attribute in a link or an area tag. In 
this case, the JavaScript must be prefixed with javascript:. This 
is interpreted when the user dicks on the link or area. 

As the browser interprets the HTML, it creates a hierarchy of 
objects representing the various parts of the web page. The 
imlxxlded JavaScript can access those objects. At the top of the 
hierarchy is the document, corresponding to the web page. 

The JavaScript program can manipulate the contents of the 
page though these objects. It can change the text that appears in 
a <TEXTAREA>. it ran change the source file for an <{MG> tag. 
‘file JavaScript can insert text into the input stream that is 
currently being interpreted as HTML 

The <SCRIPT> tag 

The general form is like til is: 

<SCRIPT LANGUAGE-*JavaSrrJ|>r I ,r> 

<l-HIDE 

JavaScript corip goc's here, 

//NOHtDK—> 

</SCRIPT) 


JavaScript and HTML 

JavaScript interpreters have been 
written to run in different environments, 
This article discusses Client-Side 
JavaScript whic h runs in a web browser. 

'Hie JavaScript axle is inside the 
HTML It am appear: 


• Between a <SCRIPT> and a </SCRIPT> 
tag. 


When the browser encounters the <$CRIPT> tag. it Marls 
interpreting the code as JavaScript The LANGUAGE attribute 
specifies that JavaScript 1.2 or later is required to interpret this 
script. This will work with most version 4 and later browsers. 

it the browser does not interpret at least the specified level 
of the language, it will try to interpret the text inside the script 
tags as HTML. To prevent that, the script is enclosed with <!— 
and —>, marking it as an HTML comment. 

When the JavaScript interpreter eneounrers <!—, it interprets 
the rest of the line as a comment. The // is another form of rest- 
of-line JavaScript comment. 


Danny Swarzman writes programs in JavaScript, Java, C++ .mri oilier languages l ie also plays Go anti grows jxrtatoes. You 
can contact him with comments and fob offers. mailio:dannys@stowlake,com. http://www.siowiiike.eom 
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Event Handlers 

Several tags in HTML have attributes whose value can Ik* 
text to he interpreted as JavaScript when a particular event 
occurs. An <A> lag T for example, can have an onMouseOver 
attribute. Corresponding to the tag is a JavaScript link object. 
When the browser interprets the tag, the text specified as the 
onMouseOver ailrihute Incomes the onMouseOver property of the 
link object. That text is subsequently passed to the JavaScript 
interpreter when the user moves the mouse over the link. 

Order of Interpretation of a Web Page 

Every HTML document contains a header and a body. The 
header is interpreted first. A common practice is to place into the 
header the Jav aScript to generate objects and functions that will 
Ik used in the body of the code. 

As the browser interprets the Ixxly, it creates the enclosure 
hierarchy of objects corresponding to the various tags. This 
hierarchy is completely constructed only after the browser has 
completed interpreting the body. 

There is an event generated when the load process is 
complete. Code that needs to be run only after die enclosure 
hierarchy has Ixrn completely constructed can run in an onLoad 
event handler. 


□ Nets rape: PeflSGlilfljn; 
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Figure 1 , Fig Soli la ire Came 


Developing JavaScript 

t o develop JavaScript to run in a web page, you need a text 
editor to create an HTML file. The script is embedded in the 
HTML code. UBEdit is my favorite, but any editor will do. 

Test the file by opening it in a browser, I start with Netscape 
because the error messages are IxUer. When you enter javascript: 
as the URL in any browser window, Netscape will open a new 
window in which to display the JavaScript error messages. 


tn Internet Explorer, you need to set preferences to see 
error messages. Each error message is displayed as a separate 
alert. Look at the Web Content subsection of the Web Browser 
section in the preferences dialog. The relevant choices appear 
under the heading of Active Content, 

As with many web technologies, you may need to make an 
extra effort to ensure that your axle works in all browsers. There 
are many different strategies for dealing with questions of cross¬ 
browser compatibility. That is lx i ynnd the scope of this article. 
The sample axle has 3xrn tested for recent versions of the two 
popular browsers running on two popular operating systems. 

Another helpful tool is a shell in which you can Lest 
fragments of code. An HTML file, enriched with JavaScript, can 
!x i used to allow the user to enter text into a text area and invoke 
the JavaScript interpreter to evaluate it, showing the results in 
another text area. An example is available on the web. See the 
references section at the end of this article. 

Tin- Evolution of JavaScript 

JavaScript is the name of a language promoted by 
Netscape to complement HTML scripts. This use of JavaScript 
is (ailed Client-Side JavaScript. Microsoft developed a similar 
scripting language called [Script, At the Lime of this writing, 
there have been five versions of JavaScript, 1.0 through 1.4 
and five versions of (Script, 1.0 through 5.0. 
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In each version, new features have been added and old 
ones broken. Insuring compatibility with the early versions is 
a nightmare. Fortunately, around JavaScript 1.2 tilings began 
to stabilize. 

The European Computer Manufacturers' Association is 
developing a standard for these languages. Both Netscape 
and Microsoft are members of the association and both have 
agreed that their future browsers will conform to the 
standard. The standard is called ECMAScripi. It also is known 
as E-262 or ECMA262, 

The first two editions of the ECMA262 report described 
a language Lhai was quite limited. The third edition is more 
comprehensive and corresponds to the implementations in 
version 5.x of the two popular browsers. 

The EC M A Script documents are more difficult reading than 
the documentation produced by the browser vendors but are 
more precise. Although they are primarily intended for 
developers of script interpreters, they are useful reading for 
anyone who wants a thorough understanding of the language. 

There are also interpreters for JavaScript that run outside of 
i he browser environment. These arc implementations that run in 
servers and interpreters imbedded inside other applications. 

The example program presented in this article, Peg 
Solitaire, works with versions of the language starting with 
JavaSc ript 1.2, The description of the language is based on 
the third version of HCMA262. 

Sqmil JavaScript Syntax 
Variables and Scope 

A variable is a container, the atom of the JavaScript cosmos, 
A container contains a value, A value can be primitive type like 
number, string, etc. or It can be an object. A variable can contain 
data of any type. 

A variable has a name, its identifier The identifier is 
associated with a scope that is either global or local to the 
function in which the variable is declared. When variables are 
created with a var keyword inside a function, the identifier is 
local lo the function. Otherwise the variable ts global in scope. 

For example, the following would create a variable: 

var 1=7: 

There are actually two actions taken by the interpreter: 

* When rhe .scope is entered, the identifier is associated with a 
variable, the value of which is undefined. 

* When die statement is interpreted, the value of 7 is assigned 
Lo the variable. 

A variable may be created by an assignment statement, even 
if the assignment statement is in the body of a function, without 
using the keyword var. A variable thus created is global in 
scope. For example: 

i - 7: 


creates a global variable and puts 7 into it. The variable will be 
created when die statement is interpreted. Hither than when the 
scope is entered. 

Objects and Initializers 

An object is a collection of ftroJxnHes, A property is a 
container It has a name and contains a value. 

There are several ways to create objects. One way is to use 
a constructor function. Constructor functions are not used in the 
sample code, but are described later in this article. Instead, all of 
our objects will be hiiill with initializers. 

An initializer is a list of properties separated by commas. 
The list is enclosed in curly braces. Consider the statement: 

vt tr blob = I color:*red", size;3 ); 

'lids creates an object with two properties named color and 
size. The value contained in die property, color, is the string 
"red", The left side of the statement, var blob, tells the interpreter 
to create a variable. The name blob is associated with the newly 
created variable. If the statement occurs within a function, the 
scope of die variable is local to the function. If the keyword var 
is omitted, the scope of ihe variable will lx* global 

A script can reference a properly directly by name with this 
synlax: 

blob,color 

or ii can use a string expression to refer Lo the property: 

blob["color"} 

Either of these references will remrn the value red. 

The value of a property can be changed by an 
assignment like; 

blob, col or - ‘’blue**; 
or: 

blob["cotot*1 “ "blue": 

New properties can be added to an object: 

blob,weight *- 3.14: 

or: 

blob ["weight"] = 3.U: 

The JavaScript object model is quite different from the 
object models thai appear in C++ and Java. For example, the 
number and names of properties change dynamically, unlike 
members and methods. There are many other differences that I 
do not discuss here. 

Arrays .Are Objects 

In a typical JavaScript object, properties are named with 
strings. There is a special kind of object in which the properties 
are named with numlxrs. These are arrays. Array initializers 
have square brackets. For example: 

var codes = [ "black", "brown", "rod", "orange" }: 
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creates an array object with four numlxTed properties* starting 
with 0. The third clement in the array, codes[2], contains “red" . 

Functions Are Objects 

A function is also an object, The initializer for a function 
object is a function definition. There are two flavors of function 
definition: function declaration and function expression* They 
both produce the same kind of object, 

A function declaration creates a new object and assigns the 
object to an identifier* The identifier b local to the scope in 
which the declaration appears. When a scope is entered, the 
function declarations are evaluated before any statements in the 
scope are interpreted. 

The form of function declaration is: 

function Identifier ( FannalFaramt orient 0 ? 1 ) { 

FunctionBody ] 

The formal parameter list is a sequence of identifiers 
separated by commas. The on? ' indicates that the list may be 
empty. The function body is a series of statements and function 
declarations. The parameter list and tody are bound to the 
identifier when die function declaration is interpreted 
An example of a function declaration is: 

function a { x )(return x+LI 

The function expression looks much like a function 
declaration at first glance: 

function Identi fier°P T ( FonnalParamterUsi °P l ) ( FunctioraBody 
1 

The identifier is optional and is ignored if it does appear. 
This expression yields a value that is a function object. The 


value is used by the statement in which the expression 
appears. For example: 

var a*f unction [at) ( return x+13 

works much like a function declaration except that the function 
object is created at the time the statement is executed, not when 
the scope is entered* The object will tocome the contents of the 
newly declared variable. 

The concept of considering a function as a data structure 
dates back to USP programming’s lambda expressions. These 
allow for some interesting programming styles. 

The syntax of a function call is familiar. The function name 
is followed by a list of values to be substituted for the formal 
parameter. For example the expression: 

a(4j 

will have a value of 5 regardless of the definition, if a is declared 
with either of the above examples* 

A function call is interpreted at runtime* Thus tills fragment: 

W: 

M4) 

wall also have the value of 5. 

An Idiosyncrasy of Syntax (in cash you were wondering) 

The interpreter considers any statement that begins with 
the keyword function to be a function declaration. Consider 
this sequence: 

functionU)I return x+1 J f7) 

Although this is not a proper function declaration, the 
interpreter will accept it and create a function without assigning 
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it to a container. The value of this sequence is llie value of the 
expression statement, 7, 

If the sequence starts with any other character, the part 
beginning with the keyword would l>e interpreted as a function 
expression. The following contain function expressions dial 
behave like function dills. The value in each case is 8: 

l , function(x)[return x+!!(7] 

[function Ex) t return x+1 J (7)) 


lambda Expressions in Object Initializers 

In the sample code, objects arc built using object initializers. 
The initializers for the properties are separated with commas. 
The function properties are defined with lambda expressions. 
Consider this example: 

var netterGetter * 

I 

daiaPurt;Q, 

set: function ( x ) 

1 

this, data Pan: * x: 

L 

get; function 0 
\ 

return this.dataPart: 

I 


These fund ions would be called with statements like: 

a-settarGettfir *get(1? 
ae t t«trGet tpr.net f 7 ); 

The keyword this refers to the current object. Inside this 
object initializer this.dataPart is synonymous with 
setterGetter.dataPait 

Note that the Odds of an object initializer must be separated 
wit ft commas. 

This technique achieves encapsulation of data and scoping. 
It eliminates some of the clutter involved in using constructor 
functions when you don't require them. 

There is only one copy of setterGetter. data Pari, 'litis is 
similar to the result of using the keyword static in Java and C++ 

Constructor Functions 

The usual way lo do things is to define a function that sets 
up an object* for example: 

function SatterGetter [) 

I 

this.dalaPari ■** Or 
thin,sol = function ( x ) 

t 

lUia.dataPart - x: 

I: 

this.get - function 0 
I 

return thic.duioPart : 


A call to this function with the new keyword will create 
an object: 

var iiSetterCetter * new SetterGetter0; 

hirst a new object is created with default properties. Then 
the constructor is interpreted. This constructor adds properties lo 
the newly created object. The this in the SetterGetterf) function 
refers to the newly created object. 

Thus aSetterGetter will acquire properties ; 
aSetterGetter.set(). aSetterGettergelO, and aSetterGetter.dataParL 
This mechanism liIIows the creation of something similar to 
an instance of a class in oilier languages. There is also a 
mechanism similar to inheritance. For a thorough discussion 
about how this works and the contrast with classes in C++ and 
Java see the Netscape Documents listed in the references section. 

The objects in our sample code are each unique. We don't 
need anything like classes and tan get rid of the extra steps 
required to use constructors* 

Pl-ti SOUTAFRF 

About the Game 

The play area consists of holes containing pegs. They are 
arranged in a cross consisting of 33 holes. See Figure l. The 
game is centuries old and has attracted the attention of many 
great minds Gottfried Wilhelm Leibniz, Elwyn lierlekamp, 
John Conway, Martin Gardner, to name a tew. 

In the beginning every hole is filled except the one in the 
center. A move consists of peg jumping over an adjacent peg 
and landing in an empty hole two spaces away in one of four 
directions. There are no diagonal jumps. The jumped peg is 
removed, Hie object is to remove as many pegs as possible. At 
the end, one peg remaining constitutes a perfect score. 

About the Program 

The sample rode displays the board in a web page. To view 
the script, open Lhe well page in your brow ser and choose die 
menu command to view the source. Tile URL is: 

http ://www.stowla kexom/Sol ita i re 

The program does not play lhe game. It does enforce the 
rules and performs housekeeping. Making a play is a two 
step process: 

* Hie user clicks on a peg to be moved. A smiling fat e appears 
on lhe peg, indicating that it is selected. 

* The user clicks on the hole where the peg is to go. The peg 
moves and the jumped peg disappears. 

There are rollover effects to indicate legal selections* 

lhe sample is completely contained within one HTML 
document. There is JavaScript code in lx>th the head and body. 
Hie objects that do the work are defined in the head In the 
body, JavaScript is used U> generate HTML 
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Objects Defined in the Head of the HTML Document 

There is a set of variables assigned to object initializers in 
the bead of page, 

Peg Board keeps track of which holes contain pegs, 
PegGame makes moves and interpreLs the mles, 

PegDi splay displays the board on Lhe screen. 

PegControl keeps track of wliich peg is selected and displays 
if accordingly. 

PegMouse handles mouse events. 

PegMake generates the HTML for the playing board. 

The statements defining these objects appear together* 
enclosed in IITML script rags specifying JavaScript 1.2. 


PegControl.Sclort ( where } 

PegDisplay.Jump ( where, delta ) 

PegDispla y.Red t aw t) 

Peg!) isplay. Reset <} 
i'egHoujre.Dver ( where ) 

PegDisplay.Out ( where ) 

FegDisplay.Click ( where ) 

PegHaker .M;ikePlace ( where } 

Pegttaker.MakeBow ( left ) 

PegHaker.MakeBoard () 

PegKaker.MafceEod y t) 

Resizer.Install [) 

ResUer. Resize () 

where, from, and left are numbers identifying peg positions, 
delta is the difference in peg numbers of adjacent peg positions, 
what is a string representing the contents of a j>eg position 
emptyHole, hasPfcg, selectedPeg. etc. 


List cjf Functions 

Some of the functions listed Ixdow are described in this 
article. For the others, see the source code on the web. 

PegBoard. TsEnipty ( where ) 

PegBoard.HasFeg ( where ) 

PegBoard■KemovePflg C where ) 

FegBoard.PutFeg ( where ) 

PegBoard.ClcneFouilIon 0 
PegGame.Jump ( tram. delta ) 

PegGame.r^Legai ( from, delta ) 

PegGamn.JumpExistsFrom ( from ) 

PegCame. InfteltaSet t delta ) 

FegCame.AruThereAny () 

PegGame.Reiresh t) 

P e g Di s p 1 ay. Load 1 mugen () 

PegDisplay.Showimagc ( where, what ) 

PugDbi pi ay T Normal Inuige ( where } 

PegDiaptay.ShowNormal ( where ) 

PegUifiplay.ShowOver ( where ) 

PegDisplay.ShowGameOver (J 
PegDisplay.ShowSel acted ( where ) 

PegDlsplay. PeghtnniberToHame ( where J 


Generating HTML Code for the Pegs in the Body of the 
HTML Document 

Listing 1: The PegMaker object 

FcgMakcr 


PegMaker = 

t 

tt 

//Generate the strings m make the board in HTMl 

// 

//An cxampk t suppose where is 26 

ft 

it <A I 

// oiiMt>uscOn?r=*sefLstatus^; return lVgMousc,Ovcf(26} 

// (HlMt juscC) ut=I'egM \ lUafc C>uU 26) 

//1 in MouseDovv itse lf.siaiitH=": return PcgMoiis*' Click(26» 

// <IMG SRC=‘ 

// 


MaJtePlace: function ( where ) 

i 

var result ~ *<A HREF-^f w 1 : 
resuli+= 1 onMoimeGver^' 

f ‘“seif .statufi^* l “*“*+*: reLurn PegMouse. 


Fight Boredom 

Let’s face it: Much of programming is boring 
and repetitive. Well, that’s where the right 
tool can save days, weeks, or even months 
of your valuable time. 



Model- View-Controller 

AppMaker's generated code uses the MVC 
paradigm. It separates the user interface 
from application logic, making code easier 
to write. You deal only with abstract data; 
AppMaker takes care of the user interface. 


AppMaker 

Your Assistant Programmer 

AppMaker makes it faster and easier to make an 
application. It’s like having your own assistant 
programmer. You point and click to tell 
AppMaker the results you want, then it 
generates “human, professional quality code" 
to implement your design. 


Scriptable Applications 

AppMaker generates the 'aete' resource and 
generates code to access your data 
(Properties and Elements in the Apple Event 
Object Model) and to handle Events. 

Just $199 from www.devdepot.com B*0»W»E»R*S 

Development 

(>.0. Box 929. Grantham, Nil 03753 • (603) 863-0945 • FAX 863-3857 
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Overt* I where + *) m *: 

result+= * eiiHouseOut ^ 4 

* * w PegWouse. Out! * + where + *)***; 
result4- ' onKouseDovn~* 

+ 1 "self.status** + "**" 

+*;return PegWouae.Click ( 1 + where + *)*>■; 
result+- *<IMG SRC= H1 + PegDispiay.Normallflagefwhere) + 
result+= * BORDERED** HEIGHT=”6{T W1DTH='60"'; 
result 1= * tfAKj£^* 

+ * M ‘ + Pe gDisplay * Pe gNu mb erToName( where )+ *->■; 
result += 1 </A>'; 
return result; 

J, 

MiUteRow: function { left ) 
var result ^ 1 <Ttt> 1 ; 

for f var where-left; vhero<(left+ 7 ); where++ J 

result += '<TD>‘ + th fs,Make?lace ( where ) + 'OTO) 1 - 
result +-■ ‘</TR>*: 
return result; 


HakeBoard: function (J 
t 

var result = STABLE BORDER-^tT CELLSPACING^O" f 
+* CEUPABDING“ ,, (PV; 

for ( var vhere^24; where<101; where+^ 11 J 
result +- rhis- MiikeKow ( where ); 
result +“ *</TARLE>'; 
return result; 
h 

MakeBody; function0 
I 

var boardHTML - this.MakeBoard[}; 
document, write 

( *<BQD? BGC0L0R=”#A7DDDir>* ); 
document,write { *<DIV AUGN* ,, center w >’ h 
document,write ( ■<?>' ); 
dor ti incut, write ( board HTML ): 
document,write ( ‘</P>‘ J; 
doemuent.write ( *</LUV>* ); 
document,write C *</BQDY>* ); 

J 

The PcgMaker object constructs the body of the weh 
page. MakeBodyO is ihc lop level function. It writes a series 
of strings to the current document. When the call to the 
document.writeO function is executed, the generated HTML is 
fed to the browser to be interpreted. 

MakeSodyQ wraps die board with tags to display the board 
centered on the sc reen and with Lhe appropriate background. 

MakeBoardQ constructs a string which contains the HTML 
tags to generate a table. 

The table is a square army ot cells. We assign numbers to 
each of the cells; 

24,25,26,27,28,29.30, 

35.36,37.»..39,40,41, 

46,47,48,49,50.51,52, 

57,58,59,60,61.62.61. 

68*69,70.71,72,73,74, 

/9,80,81,82.81,84,85, 

90,91,92 *93,94,95*96 

c reating a 7x7 area inside an 11x11 frame. 


These elements correspond to the playing area: 

26,27,28. 

37.38*39, 

46.47,48.49.50,St,52. 

57.58.59.60.61,67,63. 

68,69.70.71,72,73,74, 

81,82,83, 

92,93,94 

Position 24 is used to display a message when there are 
no more legal moves. Position % is a reset button. The other 
elements take no rule in ihe game and display the image 
noHole. I his numbering system simplifies the move 
calculations done by the PegGame object. 

MakePeg(} generates a string For each cell. It consists of an 
<A> tag which contains an <IMG> tag. Tile <IMG> tag has a 
NAME attribute formed by the Peg preface followed by the 
number. For example, NAME= h Peg261 

There are attributes, onMouseOver, onMouseDowm and 
onMouseOui* assigned to each <A> tag . The value of each of 
these is JavaScript axle that calls functions that are defined in 
the header, PegMouse.Over(), PegMouse.Outf), and 
PegMou$e,Click(). The peg number is passed as an argument to 
the PegMouse function. 

The Main Program 

Listing 2: The Main Program 

PegDispby 

<!- The body will be generated by this script, -> 

<SCRIPT LANGUAGE^"JavaScriptj.7"> 

<1-HIDE 

Rer ; >ier, Install 0 ; // Su uji event lurndJcr for resizing 

V c gU i s pi ay, Load T m ges U ; // Preloads i mages 

J gMaker. Make Body {); // (enervate iags-USa prdoaded images 

PegControl, Reset U ; // Set up rhe Ixurd and show ii 

//NOtltDE—> 

(/SCRIPT) 

Instead of having a IxxJy in the HTML file, rhere Ls a 
JavaScript that creates the hotly. This is the top level of the 
program, playing the role of main(). See Listing 2. This code calls 
functions defined in the header. 

The script initializes an event handler for resize events in 
Netscape and then loads the images that can appear in the 
hoard display. Once these are in place, the HTML that will be 
the body of the page is generated by the call to 
PegMaker.MakeBodyO. Once the tags are created, the board is 
set up in the starting position. 

Swapping Images 

Listing 3: The PegDisplay Object 

PcgDLspUy 

PegDisplay = 

1 

// Hk paths for images dial can go on boaid. 

ItnageList ; 
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n pH ole:*PegSulitG1T s/nohole.gif"* 
ever Role: "FegSo i ilGJ f a/nverhole«gi f **. 
emptyHo1e;"PegSoiitGifa/emptyhole»gif^* 
tiasPeg: "PegSoiitGlt s/haspeg * gif", 
overPeg:"PegSo1ItGits/over peg,gif ". 
aelecte4Peg:“PegSolitGifs/selectpeg.gif". 
gameOver r^PegSol itGifs/garnet)ver- gif'" ♦ 
reantButton:"PegSotitGIfS/reset.gif 1 * 

1. 

Storedltuagee ; new Array ()* 

// Make sure nil the Images art in memory Doing liiis makes 
// the display of these images smooth 
LoadImages : function 0 

for ( imagePath in PegDisplay.loageList ) 

PegUisplay .Stored image,- [ Image Path.] - new Image (): 
PegDi s play. Stored Images l itiagePathJ .sre ” 
Peghisplay.ImageListTima go Pat hi: 

I 

L 

// Show specified image nod place 

Shovlmago: function ( where* whet ) 

[ 

var name - this,PegNumberToMarne(where); 
document[namoj*src- 
this. IraageMst [what]: 

1, 

}} Show the no rollover. not selected image for where 

NormalImage: function f where ) 

I 

var what - 

Pegftoerd*TnEmpty t where ) 

? “empiyHote* 

% Peghoard.HnsPeg ( where } 

? “hasPeg" 

: where ™ PcgBnsrd.resetPosition 
7 ri resetButton" 

: “noHole": 
return what; 

I. 

// 

// All these Show, functions assign 
// a file path to the source for the 
// Image 

// 

ShowKortnali function ( where ) 

! 

PegDisplay.ShowTmage ( where. 

PegDisplay,No rma1Image(where) ): 

I. 

// ] h I Ur hole thiit can lx destination of current selection or 
// peg that can make a legal move 

ShowGvet: function ( where ) 

I 

if ( PegGsmc* TfiLegal [ PegControl.selection. 

(where-PegControl .selection)/?. ) ) 

this . Showing** ( where, "uvertfole" ); 
else If ( wheref“PcgControi.selectJon 
ith PegGame.JumpExlsi-HFrom t where ) 1 
this,Shovlaage ( where. “overPeg“ ); 


ShowGameOver: function () 

t 

thls.ShowImage { PegBoard.gameOverPosition, “gameOvnr ): 

L 

ShowSeloeted: function ( where ) 

i 

if ( where ) 

this*ShowIiiag<? £ where. 11 selected Peg" ); 

L 

// Form the name to refer to the peg, 

PegNumborToName : function { where ) 

I 

return M Fog“ + where; 

I 


I 

Tltc program reacts to mouse events by changing the .gif 
dial is assigned to one or more peg positions. Tlie .gif files are 
referred to by these names: 

• noHole is the image displayed outside the playing area. 

* emptyHole is the normal appearance of an empty hole* 

• overHote appears when the mouse is over a hole to which the 
currently selected peg can jump, 

* hasPeg is the normal appearance of a peg. 

* selectedPeg shows a peg ready lo move* 

• overPeg is displayed when the mouse is over a peg lor which 
a legal move exists-iIuit is* a |x j g iJnil can become selected, 

• gameOver is displayed in |x>sition 24 when there are no legal 
moves on the board 

* resetButton is always displayed in position 96. 

These are shown in Figure 2. 
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Hu* function Peg Display. Load I mages() sends requests to load 
tiie gif files. It is called before they are actually needed to 
display. This parents an annoying delay the first time the iistr 
moves the mouse over a selectable peg. For each .gif that it is 
loaded, a new Image object is created and assigned to an 
element of the array PegDisplay, image List. This is the same type* 
of object that the browser creates for an <IMG>. 

The actual request to get the file comes when this statement 
is executed: 

PefiDlaplny, Star edlnta Res,sr c - 
Pe&Difipl ny . Im&eList fiiruigei'athj ; 

lliis assigns a URL from ihe PegDisplay.lmageList to the sre 
property of the newly created Image object. Image objects watch 
for a change in the sre property. When it changes, a handler in 
the Image object tries to gel the image data. If the image hasn't 
already been loaded, it sends a request to lire server to get the 
specified image file. If the Image object was created by an 
<IMG> tag, Ihe display on tire screen will also change. 

Ilte Image objects created by tags in tire peg IxkirI each 
have a NAME attribute based on the position number. The value 
ot that attribute is used as the name of a property in the 
document object, l or example, document["Peg26"] refers to Image 
object created by the browser when it interpreted the <IMG> tag 
that specified the attribute NAME="Peg26". when the name of a 
.gif file is placed in the sre property of that object, the image 
displayed in position 26 will change accordingly. 



Figure 2 /mages that are swap/K’d in the board display. 


Conclusions 

JavaScript has some powerful features that make it an 
interesting programming language, and it offers many choices 
for programming style. Even if you've developed a gotxl 
understanding of how to create a lucid program in C++ or Java, 
you’ll fine) that JavaScript presents its own set of challenges. 

This artic le showed iftat a practical program am lx- created 
using lamlxla expressions. They offer a means to create clean 
axle. I here ate oilier uses for lambda expressions, this article 
showed only one application. 


Some of the mechanics of interaction with the browser were 
also demonstrated. As the standard for web pages evolves, the 
role of JavaScript will grow. We on only hope that the cross¬ 
browser compatibility problems will alxite. 

References 

The code described in this article is available at these 
locations: 

• http://www.maclech .com/editorial/filearch i ves. html 

• http://www.stowlake.com/Soiitaire 

Choose the menu command from your browser to view 
the source. 

If you work with JavaScript, you will need to download the 
dcxumentation on the net. Then.* are several ixioks, though the 
language is a little too new and still clumging too fast for Ixxiks to 
keep up. My favorite is JavaScript, the Dejtmim Guide by David 
Flanagan, published Ivy O’Reilly, although it is not definitive. 

Netscape publishes a variety of documents on JavaScript. A 
goexi starting point would lx* the Client-Side JavaScript Guide: 

http://developer.netscape.com/docs/mdnuals/js/dient/jsguide/contents.htm 

Microsoft calls its version of JavaScript JScript. 
Documentation is at: 

http://msdn.microsoft.com/scripting/default.htm7/scripting/JScript/dDC/J5toc.litm 

Ihe official standard is ECMAScript. The publication of the 
standard lags Ixrhind the implementation in browsers. The 
features illustrated here will lx.* descrilxxl in the third edition of 
the F.CMA standard. See: 

http://ecm3.ch/stand/ECMA-262.htm 

A shell to test axle fragments in JavaScript is available at: 

http://www.stowlake.com/JavaScriptShell/ 
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I NAVIGATION 
SERVICES 


by Thurman Gillespy Ut, M.D. 


Updating Navigation Services Sample Code 


On the Road to Carbon 
Compliance 


Introduction 

A recent project gave me an excuse 
to delve seriously into the Navigation 
Services (NavServices) SDK for the first 
time. The SDK includes three example 
projects (Sampler, St Example, and 
SimplcTexr) that illustrate the NavServices 
API. During routine debugging of my 
code, however, I discovered multiple 
“writtHo-nlT hugs that had originated in 
the example projects. This article 
describes the steps you need to fix those 
errors and to update the projects to work 
with CodeWanior Pm 1 and Universal 
Headers 3*3 For a pointer to the 
NavServices SDK, see the References 
section at the end of this article. 

Sampler 

Sampler is a small C program that 
demonstrates to use the NavServices API 
in a document-based application. It uses 
NavServices functions to elicit files from 
the user, save files, and prompt the user 
to save or discard changes to a 
document. It also shows how to use 
NavServices functions to let the user 
choose a folder, volume, or file-system 
object, Sampler is a very good place to 
start learning how to use NavServices. So 
let’s make Sampler usable! 


Update Access Paths 

In the Access Paths panel of the Sampler.PPC Settings dialog 
box; remove the 'Shared Libraries' and ‘Cind tides’ paths from the 
User Paths list. They are not needed. Then change the System 
Paths to: 

[Compiler I :KadJS Support; 

[Compiler] 

Save the changes to this panel by clicking the Save button. 

Implied Int No Longer Allowed 

In Templates.c, there is an implied return value of type int to 
the main function that is no longer legal In C++. Change: 

roainO 

to: 

int main(vcOd) 


Runtime library Changes 

Change the MWC Runtime, lib library (which is no longer 
present) to MSL RuntimePPClrb, 

Add a Header File 

Universal Headers 3.3 include the new header file 
ControlDefinitions.h, which contains some constants previously 
defined in the file Controls.h. So add the following lines to the file 
Common.h: 

ffifndef CQtiTROLDEFINTT 

//include <ControlDeMnitions,h> 

#endif 


NavCBRec Field Change 

Somewhere between "then and now", the fields in the 
NavCBRec structure changed. In file.c and menu.c, there are a 
total of 10 NavCBReePtr variables to update. Change: 


Thurman GiUcspy 111 is a radiologist at the Veterans Administration Puget Sound Health Caro System in Seattle, Washington. 
Me on he reached at tg3@u. washtngion.edu 
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MacBuyt com 


As Easy as 1-2-3 
Whether you're searching for a 
product review or finding the Pick 
Of The Day, its easy with 
Mac Buy corn's clean user interface 
and intuitive navigation. 


Convenience and Value! 

The latest and Lowest prices from 
Leading Mac resellers. Plus, 
convenient links to their sites so 
you can purchase the product you 
want instantly! Mac Buy com tells 
you how to shop smart 


Powerful and Easy-.., 

to-use search engine. You can 
search by product or vendor name, 
or use the Power Search button to 
search by multiple criteria, such 
as rating and price. 


Support from Apple 

Literally. Built with Apple's 
WebObjeCts, MacBuy.com is solid 
as...well, a rock. 
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cal I ByckFanns - >eventDa1 a - event 

to: 

cailBackParas >eventData, event Da LaFarms * event 


Duplicate cfrg Resource 

A ‘cfrg' resource Ls defined in TempJatePPC.r. 'lliis definition 
is no longer needed because rhe CodeWurrior JDK now 
generates the correct resource. I simply commented out the 

definition in Template RFC. r. 

r 

resource d'rjC(O) { 

I 

kPowcrPC, 

kftiJJUb, 

kNt > Ve rsmn Nu m ,k No Vcrsk mNum, 

11 , 0 , 

kl sApp. ki JoUtsk Mat , kZen * )ftsc t, kWhoidwk, 

“ Template" 

J 

I; 
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AEGetDescData Write-to-nil Errors 

AEGetDescData (defined in Common s) is a utility function 
that extracts a DescType of type typeCode from the AEDesc. In 
Sampler, it is used to extract an FSSpec from the AEDesc. Listing 
I shows the original function. 


t MK I a w o I r Ijc c or mai*uv m * * i n r * av a h 

23670 Catabamw Rood ■ CnLihiumfi, CA 01302 

TH; HJ8/222-03G5 * FjiklHI6/501 I (m 

Got Software? 

I Nccd help safeguarding your software? If you're developing 
sofiwiUt, you need your valuable work protected with 
copyright and trademark registration. Then, when you are 
ready to sell it, you can protect yourself further with u 
licensing agreement. 

I ani a California Lawyer focusing on Intellectual 
Property, Corporate, Commercial, and Contract l«aw t as 
well as Wills # Trusts. 

Please give me a call or an e-mail. Reasonable fees. 

The Law Office of Bradley M. Sniderman 


Visa 

Master Card 

E-mail: brad^s itiderman.com ■ Internet: www, snider man. com 






listing 1: Getting data from an AEDesc structure (before) 


AFGetDescDau* 

OSErr AEGetDescData(const AEDesc *desc. DescType ’typeCode, 
void 'dataBuffer, ByteCount maxtwumSize. 

ByteCount *actualSize) 

I 

* typeCode = desc MescriptorType; 

Handle h = (Handle)desc >dataHandle; 

ByteCount dataSize = GetHamileSize(h): 
if (daLaSize > maximmnSizc) 

’actualSize ~ maxlraumSIze: 
el se 

*actuai5ise = daraSize; 

Bloc kMoveData{* h, dataBuffer T ’actual Size): 
return noErr; 


The function is acceptable, except for a complete lack of 
any error checking (a common practice in developer example 
code). However, AEGetDescData is called 10 times with two 
NULL pointers (menus.c). 

if ((theErr ^AEGetDescData f fcresultOesc* NULL. 

& f I rial ES Spec, eizeof ( FSSpec } , NULL )) noErr)... 


This code fragment results in two writes to nil (typeCode 
ant) actualize) and one read from nil < BlockMoveData). Bad 
JVinn, indeed for a fix, 1 simply check for the NULL parameters; 
I also added a few other error cheeks for good measure, as 
shown in Listing 2. 


Listing I ; Getting data from an AEDesc structure (after) 

U-u.ihL^thu.i 

USErr AEGetDescData (conn 1 AEDesc *desr . UescType 'typeCode. 

void *dataRuffer. ByteCount roaxInumSize, 

^ ByteCount ’octualSize) 

Handle h = NULL; 

ByteCount dataSize = 0, 

bytesToCopy 0: 

OSErr err = I; 

// check lor invalid NIIIJ. handles or pointers 

if (desc — NULL || desc->dataHandU> — NULL I 
dataBuffer — NULL) 
return niUtandieErr: 

// |$et tltr size of ilk- object, cheek fur errors 

h ” (Handle)desc >dataHandle: 
dalaSize = GetHandleSize (h) : 
err — MemE error 0 ; 
if (err != noErr) 
return err: 

// determine how many bytes to copy 

if (rfaLaSize > maximum?)! ze) 
bytesTaCopy = max ImuroSize: 
else 

bytesToCopy - dutaSize: 

// copy object from the handle to the buffer 

BlockMoveData(*b. dataBuffcr, bytesToCopy); 

// return type code and number of bytes copied, 

// if pointers are nut NULL 

if £typeCode r~ NULL) 

“typeCode * desc■>descriptorType; 
if (actualSiae f- NULL) 

“actualSize = bytesToCnpy; 
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return noErr: 


AEGetNthDesc Write-to-nil Errors 

In Sampler, AEGetNthDesc writers to nil 11 times (files.c, 
menus.c) because the fourth parameter, a pointer to ao 
AEKeyword structure, is sei to NULL 

AEG&tWrhDftBcC&CtheKeply.eelert.ion), index, typeFHS* NULL. 
4resuitl>essc) 

To correct this error, simply add an appropriate AEKeyword 
parameter, 

AEKeyword aekw; If mil used 

AEGetNthDesc(6(UioReply.selection), index, typeFSS, 
fcresul LDr.sc.) 


Sampler CFM68k 

Eor the Sampler.68kCFM project make the same changes 
to the access paths, then update the obsolete libraries to the 
correct versions, 

ttorhLibCFtt68k(4i/ad) .Uh —> MathLibGFHBSk 

£4i 8d).Lib 

HSL CLCFKfjflkFar (4i/8d), Lib => HSL 

C*CFH68kFs(4i 8d) .Lib 

MWClWSkRunt line* Lib => MSL HWCFM6BkRmu i toe .Lib 


StExample 

The SlExatliple project is a C++ example of using 
NavServiccs that is less complete than Sampler, The StExample 
project is also easier to update, 

* Update the User Paths as you did for Sampler 

* Update the Navigation library to NavigationLib. 

* In HelloWorkicp, the last parameter to StNavGetRIe must be 
changed from long to (void *), Change: 

StNavGetFile I { foerr. &specs* StnumspeCfl* ktdopen, 

&nttvreply, false , true, krdevf, nil* 
nil. tih, Oxaabbccdd); 

to 

Utn L 3 ?. ustOat “ Oxaabhccdd; 

StNavCcLFtle gfl[ &err, &speC3* &rmmspecs, &rdopc?n, 
fimavreply. false* true* Ardevt* nil, 
nil * tlh, (void ‘HusrEat ); 

* Ihere are two write-to-nil errors, IkhIi in StNavSorvices.cp. 
Change Lhe NULL fourth parameter in the call to 
AEGetNthDesc to a valid AEKeyword pointer 

SimpieTexi 

Tlie Simple'! ext project uses the obsolete OuickDrawGX, 


and a dated Maclncludes.h [leader. I decided it wasn’t worth the 
effort to update the project* 

Checking the Resuit 

To see the wrile-io-nil errors, drop into Macshug and invoke 
the EBBE (Even Better Bus Error) dcuteL 

EBBE on 

EBBE is ON (usJn^ the value $681?168Ft with a task rate of 
//17 milliseconds) 

Then run the umbered Sampler application as delivered in 
the SDK. You should see one or more wriUMO-nil errors in every 
call to NavScrvices. Both QC and Spotlight (Onyx Technology) 
will also catch the errors. 

The FREE dcind has detected that location $0000 
luio been overwritten 

After making the corrections described here* run this test 
again on the compiled example applications and on any of your 
code based on the SDK sample code. The write•lev-nil errors 
should be eliminated. 

References 

Navigation Services SDK 
<http;//developer.apple.com/sdk/index.htnnl> 

Onyx Technology 

<http://www.onyx-tech.com/> iO 
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seven times faster 


free demo 
www.onyx-tech.com 


Find memory errors automatically in source 
Code Fragment Support a 

Leak Detection G 

loolbox Parameter Checking jg 
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support of this position, he trotted out statistics 
showing that a full 88% of iMac users arc up and 
running on Lhe Internet with 66% having made a 
purchase via the Internet. My post WWDC research 
shows that these numbers compare very favorably with 
what is happening in the WinTel work! in terms of 
Internet usage. 

Moving to the QuickTime front, Steve focused on 
pushing QuickTime as “The Leading” multimedia 
standard on the Internet, Speaking to this issue he 
bombarded us with statistics on the number of 
downloads, adoption in CD-ROMs, lists of standards 
supported and features available, and a plug for 
Disney's now “famous” Toy Story 2 CD distribution via 
Frosted Cheerios boxes. 

All in all, it is clear that a lot is happening in the 
world of QuickTime. If QuickTime isn't “The Leading" 
multimedia standard, ii is definitely “A Leading” 
standard with a strong shot at the Number l slot. 

It’s the Web Stupid! 

In my viewpoint that appeared in MacTeeh the 
week of WWDC 1 let you in on Apple's best-kept 
secret: WebObjects. I am glad that I did it then, 
because following WWDC the last thing WebObjects is 
K ..Js Apple’s best kept secret". 

Leading up to WWDC Apple promised they were “turtx> 
charging” and would let us in on die details at WWDC. 

Well, Apple has definitely taken the wraps off 
WebObjects and is letting the world in on the 
WebObjects secret. 

First and foremost, they announced they are 
cutting the price of WebObjects. in the past to gel an 
unrestricted WebObjects deployment license for a 
mulli-processor system cost a cool $50,000. Despite 
this price lag, because of the power of WebObjects. it 
is the Number I web application service on the market 
wiLh over 3,000 high-profile customers. Bui Apple 
wants to grow this market and their new price of $699 
for a development and single deployment license is 
going to blow things open. 

Second, they announced that WebObjects is going to 
be a pure Java platform with the advent of WebObjects 
5 For Java. As part of this move they will be qualifying 
WebObjects for a Linux platform (likely Red Hat Pro 6,2) 
in addition to the already supported Mac OS X, Mac OS 
X Server. Windows NT, Solaris, and HP-UX 11. 

Apple backed up its WebObjects rheLortc with 18 
WWDC sessions focused on WebObjects. Though they 
were in the smaller “j” facilities, the space allocated to 
them on the WWDC schedule and the standing room 
only crowd of developers at most WebObjects’ sessions 
testified to how serious Apple and its developers are 
taking WebObjects. 


If Apple — in the iMac — has the best Internet 
client around, they have definitely matched it on the 
server side with WebObjects, It will be interesting to 
see how they work to combine the two and continue 
to move “beyond the box" in the future. In any case, it 
is clear that Apple gets that “It's the Web Stupid!” 

A Little, Sup? Ok is it? 

Steve closed off his keynote by focusing our 
attention on Mac OS X. The highlight of this section 
was his announcement of a “developer ready" — 
“...with 99% or developers finding 100% of the APIs 
they need../’ — Developer Preview 4 (DP 4) of Mac 
OS X and a “slight” revision to its schedule. 

Throughout his overview of Mac OS X and the 
demos Sieve stressed again and again that Mac OS X is 
"developer ready", and that you can start developing 
for Mac OS X today. That said, lie also made clear that 
Apple is listening to customer and developer feedback 
and revising Mac OS X based on our feedback. He gave 
proof to these words when he showed off the changes 
in Aqua that has resulted in a much improved user 
interface that were driven in large part by customer 
and developer feedback. 

Steve also announced a revision to the Mac OS X 
schedule. Instead of Mac OS X 1.0 shipping this summer 
as announced as MacWorld SF, we will be treated to a 
public beta of Mac OS X starting sometime this summer. 
Mac OS X L0 will ship in January of 2001 and will be 
available, “on some systems’, as a "pre-load option". 

The real news here isn't the shift to a public beta this 
summer. The reality is as 1 noted in my post-MacWorld 
SF Viewpoint - that no matter what it is called, the first 
release of Mac OS X will be treated as a public beta. We 
won't be seeing wholesale adoption of Mac OS X until 
well into the year 2001. 

Rather, the real news is that Mac OS X 1.0 wall not 
be pre-loaded on all systems starting in January 2001. 
For me this begs the questions: “When will Mac OS X 
be pre-loaded on all systems?" and “What does Apple 
expect the Mac OS X adoption rate to be?" 

So, did Apple — as the rest of the press trumpeted — 
slip the schedule for Mac OS X? In name. 1 must say yes. 
But in reality, 1 would have to say no. That said, they are 
slowing down what was an extremely aggressive adoption 
strategy by not pre-loading Mac OS X on all systems 
starting in January 2001 

The Bottom Line 

So, what is the bottom line out of this year’s 
WWDC? Simply put, things are going well. The 
Macintosh is alive and well, Apple is growing, and we 
can expect to be able to gather in San Jose for WWDC 
the foreseeable future. HQ 
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in one 


The MacTech CD-ROM with 
THINK Reference is the 
essential reference resource for 
Macintosh programmers. This 
CD includes the THINK 
Reference personal database 
system and a wealth of 
Macintosh programming 
databases, featuring almost 170 
issues of the journal of 
Macintosh programming — 
MacTech Magazine.This release 
also features the THINK 
Reference Compiler, which 
allows you to compile HTML 
files into your own compact, 
searchable THINK Reference 
databases, and the THINK 
Reference Collector for building 
new Mac OS API Databases. 


with THINK Reference' 
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development revolution . 1 


You're part of the movement. 

At the core you'll find two innovative 
technologies allowing you to deliver the most 
comprehensive software solutions available - 
4D and WebSTAR. 


Time is short* Seize the moment. 

Maximize your efforts using revolutionary 
development tools and Internet Servers that 
deliver now and into the future. 

Don't waste today. 

Download your future. Ignite your potential. 


See us at 


Macworld Expo 
New York 
Booth 1855 





The fate of the company is in your hands. 

Every second counts when you’re competing at Internet speed- 
And the fester your Web application is developed, deployed and 
maintained, the fester your competition will drop out of sight. 

The solution? Use Pervasive Softwares Tango 2000 to develop 
your ideas with double the speed of any other development software, 

* Visually develop applications on Mac, and deploy on 
Mac, Windows, Linux and Solaris 

* Advanced XML support 

* Connect directly to Filemaker or any ODBC database 

* Extend applications with javaBeans 

* High perform ance Tango server scales with dus ter support 


Give yourself the same competitive edge that Tango has 
given leading companies Like Apple Computer^, thegJobe.com M 
and Harbor Freight Tools™ 

Download your Free Tango Demo today! 

Grab the time-saving advantages of Tango 2000 absolutely 
FREE Visit our Web site and download our FREE fully functional 
Tango 2000 demo. Or call us now to get your demo on CD, 

www.pe 1 rosive.c 0 m/ 5 peed or 1-800-287-4383 

Hurry! This offer ends soon. 


PERn/ASIVE 

\S0FTWARE 
The Freedom lu Create Application! 
for Everyone, Everyth#! 


Apqto Computer is a regEsterarf ted«T*ifk of Apple Computer. toe . tht?0lob&,com s $ trerjemark of thegtote.com, Inc.. Harbor FrelflM Toot* e a iradamork ol Humor Fright Topi*. 









